Building a Docs-as-Code Workflow With Markdown, Mermaid, and GitHub Actions

The team’s new workflow anchors documentation in each repository’s /docs folder, pairing Markdown files with source code and wiring a GitHub Actions job (docs‑ci.yml) to lint links, enforce formatting, and fail builds on broken references. By embedding Mermaid.js syntax directly in the Markdown, architecture diagrams are regenerated on each build, while OpenAPI/Swagger annotations and Protobuf files produce up‑to‑date API reference pages during the CI step. After merge, static site generators such as MkDocs Material or Docusaurus aggregate the scattered Markdown into a single internal portal. The concrete outcomes are striking: onboarding that once took two weeks now finishes in under three days, and 85 % of architectural pull requests now include a matching .md update in the same commit, ensuring documentation evolves lock‑step with code.

This shift reflects a broader “docs‑as‑code” movement championed by companies like GitHub, HashiCorp, and Stripe, which treat docs as version‑controlled artifacts subject to the same review and CI pipelines as production code. The approach also counters the “wiki rot” problem that plagues tools such as Confluence and Notion when they sit outside developers’ primary workflow. By leveraging open‑source tools (Mermaid, MkDocs, Docusaurus) and standard API description formats (OpenAPI, Protobuf), the team aligns with industry‑wide trends toward automation, reproducibility, and single‑source‑of‑truth documentation.

However, the model introduces new dependencies: the CI pipeline must remain fast enough not to delay merges, and the quality of generated diagrams hinges on developers keeping Mermaid definitions accurate. Over‑reliance on code‑centric docs may also marginalize non‑technical stakeholders who prefer richer visual editors. Watch for scaling challenges as the number of microservices grows—aggregating dozens of Markdown trees could strain static site generators, and governance policies may be needed to standardize diagram conventions and linting rules across teams.