mkdocs-architecture-docs

This repository holds templates and environment setup intended for architectural documentation development in Markdown served with MkDocs. It is designed to be used inside a VSCode devcontainer and includes automation for builds, releases and dependency updates. The included tools and plugins facilitate PlantUML & Mermaid diagrams, and Architecture Decisions Records (ADR) development.

The included diagrams are pure autogenerated examples and are not representing a real architecture.

Project structure

• .devcontainer/ — devcontainer and Docker Compose configuration (devcontainer.json, docker-compose.yml, mkdocs.dockerfile).
• docs/ — documentation sources and generated diagrams.
• mkdocs.yml — MkDocs configuration.
• requirements.txt — Python dependencies (plugins) used by MkDocs.
• package.json / package-lock.json — dev tooling (commitlint, husky, semantic-release).
• .github/workflows/ — GitHub Actions workflows for publishing and releases.
• .github/renovate.json — renovate configuration for dependency management.

Quickstart (recommended)

1. Open the repository in VS Code and start the devcontainer (Remote - Containers). The devcontainer will automatically initialize all the necessary tools.
2. Use make for the most common commands. See make help for the full list.
3. Use the installed VSCode plugins for Markdown, PlantUML and ADR preview.
4. Serve the site locally for live preview at http://localhost:8000:

make serve

5. Deploy to GitHub Pages (this is also automatically done in CI on push to main):

make deploy

6. Update lockfile locally (generate/update package-lock.json):

make lock-deps

Notes:

• This is only needed when adding new packages. Maintenance is handled by Renovate in CI.

Devcontainer and VS Code

The devcontainer bootstraps a development environment with Node.js and Python and installs dev tooling.

Recommended VS Code extensions (installed by the devcontainer):

• ms-azuretools.vscode-docker — Docker integration
• ms-python.python — Python language support
• shd101wyy.markdown-preview-enhanced — advanced markdown preview
• jebbs.plantuml — PlantUML preview and rendering
• StevenChen.vscode-adr-manager - ADR manager
• eamodio.gitlens — GitLens
• GitHub.copilot and GitHub.copilot-chat — (optional) Copilot features

If you open the repository outside the devcontainer, run npm ci locally and run npm run prepare to install Husky hooks.

Commit conventions & local linting

• The repo relies on Conventional Commits for semantic-release. Commit messages should follow the Conventional Commits format (e.g. feat(docs): add architecture overview).
• commitlint is configured via .commitlintrc.js and a Husky commit-msg hook is present at .husky/commit-msg to validate messages locally in the devcontainer.
• Use npm run commit (commitizen) to create conventional commit messages interactively if desired.

Continuous integration and publishing

This repository uses GitHub Actions to automate publishing and releases:

• Semantic releases: A semantic release is used to generated release notes based on Conventional Commits and create a new tag.

• Publish to GitHub Pages: On push to main a workflow updates tags a new releasebuilds the site and publishes it to the gh-pages branch.

• Renovate: Renovate is configured to automatically open PRs for Python (requirements.txt) and JavaScript (package.json) dependencies. It also manages package-lock.json via lock file maintenance and will use semantic commits so updates integrate with semantic-release.

Contributing

Please follow the Conventional Commits format and run npm run lint:commit or rely on the Husky hook to validate commit messages.