https://github.com/iakovn/mkdocs-arch
Example architecture documentation with MkDocs
https://github.com/iakovn/mkdocs-arch
adr-v2 c4-model mermaid-diagrams mkdocs plantuml
Last synced: 7 months ago
JSON representation
Example architecture documentation with MkDocs
- Host: GitHub
- URL: https://github.com/iakovn/mkdocs-arch
- Owner: iakovn
- License: mit
- Created: 2025-10-16T15:02:33.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-11-03T06:30:59.000Z (7 months ago)
- Last Synced: 2025-11-03T08:21:24.757Z (7 months ago)
- Topics: adr-v2, c4-model, mermaid-diagrams, mkdocs, plantuml
- Language: Dockerfile
- Homepage: https://iakovn.github.io/mkdocs-arch/
- Size: 1.05 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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:
```bash
make serve
```
5. Deploy to GitHub Pages (this is also automatically done in CI on push to `main`):
```bash
make deploy
```
6. Update lockfile locally (generate/update `package-lock.json`):
```bash
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.