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

DevFeed: [Building a Docs-as-Code Workflow With Markdown, Mermaid, and GitHub Actions](<https://devfeed.tech/articles/building-a-docs-as-code-workflow-with-markdown-mermaid-and-github-actions-106882.md>)

Original publisher: [Read original article](<https://hackernoon.com/building-a-docs-as-code-workflow-with-markdown-mermaid-and-github-actions?source=rss>)

Author: Himashi Meththasena

Published: 2026-10-29T16:49:44Z

Content type: article

Language: en

Sources: [HackerNoon](<https://devfeed.tech/sources/hackernoon.md>)

Topics: [Documentation](<https://devfeed.tech/topics/documentation.md>), [GitHub Actions](<https://devfeed.tech/topics/github-actions.md>), [Markdown](<https://devfeed.tech/topics/markdown.md>), [CI/CD](<https://devfeed.tech/topics/cicd.md>), [GitHub](<https://devfeed.tech/topics/github.md>), [MkDocs](<https://devfeed.tech/topics/mkdocs.md>)

Tags: [actions](<https://devfeed.tech/tags/actions.md>), [api](<https://devfeed.tech/tags/api.md>), [api-documentation](<https://devfeed.tech/tags/api-documentation.md>), [apis](<https://devfeed.tech/tags/apis.md>), [architecture](<https://devfeed.tech/tags/architecture.md>), [automated](<https://devfeed.tech/tags/automated.md>), [automatically](<https://devfeed.tech/tags/automatically.md>), [building](<https://devfeed.tech/tags/building.md>), [ci-cd](<https://devfeed.tech/tags/ci-cd.md>), [ci-cd-pipeline](<https://devfeed.tech/tags/ci-cd-pipeline.md>), [developer-onboarding](<https://devfeed.tech/tags/developer-onboarding.md>), [docs](<https://devfeed.tech/tags/docs.md>), [docs-as-code](<https://devfeed.tech/tags/docs-as-code.md>), [documentation](<https://devfeed.tech/tags/documentation.md>), [engineering](<https://devfeed.tech/tags/engineering.md>), [github](<https://devfeed.tech/tags/github.md>), [github-actions](<https://devfeed.tech/tags/github-actions.md>), [internal-developer-portals](<https://devfeed.tech/tags/internal-developer-portals.md>), [markdown](<https://devfeed.tech/tags/markdown.md>), [mermaid](<https://devfeed.tech/tags/mermaid.md>), [mermaid-js](<https://devfeed.tech/tags/mermaid-js.md>), [mkdocs](<https://devfeed.tech/tags/mkdocs.md>), [technical-documentation](<https://devfeed.tech/tags/technical-documentation.md>), [wiki](<https://devfeed.tech/tags/wiki.md>), [workflow](<https://devfeed.tech/tags/workflow.md>), [workflows](<https://devfeed.tech/tags/workflows.md>)

## AI overview

The article describes replacing a detached engineering wiki with documentation maintained alongside code in each repository's `/docs` directory and updated in the same Git commits as code changes. It uses Mermaid definitions for diagrams, OpenAPI or Swagger annotations for REST APIs, and Protobuf definitions for gRPC so API references can be generated during builds. GitHub Actions checks documentation in pull requests for broken links, dead URLs, and formatting; after merges, MkDocs Material or Docusaurus can publish Markdown from multiple services to a searchable internal portal. The article reports onboarding time falling from two weeks to under three days and matching Markdown updates appearing in over 85% of architectural PRs. These are the article's reported results; it gives no measurement method.

## Source excerpt

How we replaced an outdated engineering wiki with Docs-as-Code using Markdown, Mermaid, GitHub Actions, and automated documentation workflows.