{"id":32750146,"url":"https://github.com/iakovn/mkdocs-arch","last_synced_at":"2025-11-03T23:02:01.935Z","repository":{"id":319260874,"uuid":"1077663252","full_name":"iakovn/mkdocs-arch","owner":"iakovn","description":"Example architecture documentation with MkDocs","archived":false,"fork":false,"pushed_at":"2025-11-03T06:30:59.000Z","size":1106,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-03T08:21:24.757Z","etag":null,"topics":["adr-v2","c4-model","mermaid-diagrams","mkdocs","plantuml"],"latest_commit_sha":null,"homepage":"https://iakovn.github.io/mkdocs-arch/","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/iakovn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-16T15:02:33.000Z","updated_at":"2025-11-03T06:29:33.000Z","dependencies_parsed_at":"2025-10-18T16:34:41.950Z","dependency_job_id":null,"html_url":"https://github.com/iakovn/mkdocs-arch","commit_stats":null,"previous_names":["iakovn/mkdocs-arch"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/iakovn/mkdocs-arch","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iakovn%2Fmkdocs-arch","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iakovn%2Fmkdocs-arch/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iakovn%2Fmkdocs-arch/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iakovn%2Fmkdocs-arch/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/iakovn","download_url":"https://codeload.github.com/iakovn/mkdocs-arch/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/iakovn%2Fmkdocs-arch/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":282542839,"owners_count":26686795,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-11-03T02:00:05.676Z","response_time":108,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adr-v2","c4-model","mermaid-diagrams","mkdocs","plantuml"],"created_at":"2025-11-03T23:00:42.703Z","updated_at":"2025-11-03T23:02:01.924Z","avatar_url":"https://github.com/iakovn.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mkdocs-architecture-docs\n\nThis repository holds templates and environment setup intended for architectural\n 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.\n The included tools and plugins facilitate PlantUML \u0026 Mermaid diagrams, and\n Architecture Decisions Records (ADR) development.\n\nThe included diagrams are pure autogenerated examples and are not representing\na real architecture.\n\n## Project structure\n\n- `.devcontainer/` — devcontainer and Docker Compose configuration (`devcontainer.json`, `docker-compose.yml`, `mkdocs.dockerfile`).\n- `docs/` — documentation sources and generated diagrams.\n- `mkdocs.yml` — MkDocs configuration.\n- `requirements.txt` — Python dependencies (plugins) used by MkDocs.\n- `package.json` / `package-lock.json` — dev tooling (commitlint, husky, semantic-release).\n- `.github/workflows/` — GitHub Actions workflows for publishing and releases.\n- `.github/renovate.json` — renovate configuration for dependency management.\n\n## Quickstart (recommended)\n\n1. Open the repository in VS Code and start the devcontainer (Remote - Containers). The devcontainer will automatically initialize all the necessary tools.\n2. Use `make` for the most common commands. See `make help` for the full list.\n3. Use the installed VSCode plugins for Markdown, PlantUML and ADR preview.\n4. Serve the site locally for live preview at http://localhost:8000:\n\n```bash\nmake serve\n```\n\n5. Deploy to GitHub Pages (this is also automatically done in CI on push to `main`):\n\n```bash\nmake deploy\n```\n\n6. Update lockfile locally (generate/update `package-lock.json`):\n\n```bash\nmake lock-deps\n```\n\nNotes:\n- This is only needed when adding new packages. Maintenance is handled by Renovate in CI.\n\n## Devcontainer and VS Code\n\nThe devcontainer bootstraps a development environment with Node.js and Python and installs dev tooling.\n\nRecommended VS Code extensions (installed by the devcontainer):\n\n- `ms-azuretools.vscode-docker` — Docker integration\n- `ms-python.python` — Python language support\n- `shd101wyy.markdown-preview-enhanced` — advanced markdown preview\n- `jebbs.plantuml` — PlantUML preview and rendering\n-  `StevenChen.vscode-adr-manager` - ADR manager\n- `eamodio.gitlens` — GitLens\n- `GitHub.copilot` and `GitHub.copilot-chat` — (optional) Copilot features\n\nIf you open the repository outside the devcontainer, run `npm ci` locally and run `npm run prepare` to install Husky hooks.\n\n## Commit conventions \u0026 local linting\n\n- The repo relies on Conventional Commits for semantic-release. Commit messages should follow the Conventional Commits format (e.g. `feat(docs): add architecture overview`).\n- `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.\n- Use `npm run commit` (commitizen) to create conventional commit messages interactively if desired.\n\n## Continuous integration and publishing\n\nThis repository uses GitHub Actions to automate publishing and releases:\n\n- Semantic releases: A semantic release is used to generated release notes based on Conventional Commits and create a new tag.\n\n- 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. \n\n- 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.\n\n\n## Contributing\n\nPlease follow the Conventional Commits format and run `npm run lint:commit` or rely on the Husky hook to validate commit messages. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiakovn%2Fmkdocs-arch","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fiakovn%2Fmkdocs-arch","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fiakovn%2Fmkdocs-arch/lists"}