Docs-as-Code with Markdown: Complete Workflow Guide (2026)
Ship documentation from Git with Markdown — repo structure, Hugo, Docusaurus, MDX, review workflows, CI linting, API automation, and patterns documentation teams use at scale.
Docs-as-code means treating documentation like source code: Markdown files in Git, pull request reviews, automated tests, and deployments triggered by merges. No siloed wiki that drifts out of date the week after launch.
Teams at Stripe, GitLab, and thousands of startups use this model because it works — engineers already live in Git, and .md diffs are readable in PRs. When the API changes, the doc change sits in the same commit.
This guide is the end-to-end playbook: repository layout, toolchain choices, CI pipelines, review culture, and how to automate quality checks with the Markdown API so broken docs never reach production.
What docs-as-code looks like in practice
repo/
├── docs/
│ ├── getting-started.md
│ ├── api/
│ │ ├── authentication.md
│ │ └── rate-limits.md
│ └── _sidebar.md # optional nav config
├── src/ # application code
├── .github/workflows/docs.yml
└── docusaurus.config.ts # or hugo.toml, mkdocs.yml
Workflow:
- Author edits
docs/api/authentication.mdon a branch. - Opens PR — teammate reviews prose and code samples together.
- CI runs Markdown lint, link check, and spell check.
- Merge → static site deploys to
docs.example.comin ~2 minutes.
The wiki model inverts this: docs live outside Git, reviews are optional, and "doc fix" tickets lag code by sprints.
Why Markdown for docs-as-code
| Property | Markdown | Proprietary wiki |
|---|---|---|
| Git diffs | Clean line changes | Export blobs or N/A |
| Tool choice | Hugo, Docusaurus, MkDocs, Astro | Vendor lock-in |
| Offline / backup | git clone | Export hacks |
| CI validation | Lint, link check, API audit | Limited |
| Engineer familiarity | READMEs already Markdown | Learning curve |
| Portability | Obsidian, VS Code, any editor | Migration pain |
Markdown is not the most feature-rich format — MDX adds components when you need them. Start with .md; upgrade to .mdx only where interactive widgets justify the complexity.
Choose your static site generator
| SSG | Best for | Markdown flavor |
|---|---|---|
| Docusaurus | Product docs with versioning | MDX + GFM |
| Hugo | Speed, large sites | Goldmark GFM |
| MkDocs Material | Internal tech docs | Python-Markdown + extensions |
| Astro Starlight | Modern docs + performance | MDX |
| Next.js | Docs inside app monorepo | MDX remote |
| GitBook (Git sync) | Less ops, hosted | GFM |
Decision heuristic:
- React team already on Next.js → Docusaurus or Starlight
- Go/static purist, 10k+ pages → Hugo
- Python shop → MkDocs Material
- Want zero SSG ops → GitBook with Git sync (trade control for convenience)
Repository structure patterns
Flat docs folder
docs/
index.md
quickstart.md
api-reference.md
Good for small products (< 20 pages). Navigation is manual sidebar config.
Topic hierarchy
docs/
getting-started/
install.md
first-request.md
api/
render.md
convert.md
guides/
migration.md
Scales to hundreds of pages. Match URL paths to folder paths for predictable links.
Monorepo packages
packages/
core/
README.md
docs/
cli/
README.md
Each package owns its docs; root docs/ covers platform overview. Link between packages with relative paths.
Use the outline reorder tool when restructuring a large migration.
Frontmatter conventions
Consistent YAML at the top of every file:
---
title: "Authentication"
description: "How to authenticate API requests with Bearer tokens."
sidebar_position: 2
tags:
- api
- security
---
| Field | Purpose |
|---|---|
title | Page H1 and <title> tag |
description | SEO meta and social cards |
sidebar_position | Nav order (Docusaurus) |
slug | Override URL path |
draft: true | Hide from production builds |
Edit frontmatter in bulk with the frontmatter editor. Extract fields via API in CI.
Authoring workflow
Local: VS Code
The default setup for docs-as-code — see the VS Code Markdown guide:
- Markdown All in One for TOC and lists
- markdownlint for style
- Preview with Mermaid + KaTeX extensions
Browser: quick edits
Non-engineers (PMs, technical writers) may prefer the browser editor — paste from Google Docs via HTML to Markdown, preview, copy back to Git.
Review checklist (PR template)
## Doc PR checklist
- [ ] Frontmatter `title` and `description` filled
- [ ] Code samples run on latest release
- [ ] Links use relative paths where possible
- [ ] Screenshots updated (if UI changed)
- [ ] CHANGELOG or release notes linked
CI pipeline for documentation
Tier 1 — Every PR (fast)
name: Docs CI
on:
pull_request:
paths: ['docs/**', '*.md']
jobs:
markdown:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Markdown lint
uses: DavidAnson/markdownlint-cli2-action@v16
with:
globs: 'docs/**/*.md'
- name: Validate via API
env:
MDV_API_KEY: ${{ secrets.MDV_API_KEY }}
run: |
for f in $(find docs -name '*.md'); do
content=$(jq -Rs . < "$f")
curl -sf -X POST https://trymarkdownviewer.com/api/v1/validate \
-H "Authorization: Bearer $MDV_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"markdown\": $content}" \
|| { echo "FAIL: $f"; exit 1; }
done
Tier 2 — Nightly (thorough)
- Extract links — HTTP HEAD on external URLs
- Audit headings — single H1, no skipped levels
- Audit GFM — tables and task lists well-formed
- README score on root README
Tier 3 — Release branch
- Build SSG locally or in CI (
npm run build) - Deploy preview to Vercel/Netlify preview URL
- Comment preview link on PR
Link hygiene
Broken links destroy trust. Rules:
- Prefer relative links inside the repo:
[auth](./authentication.md) - Version external links — pin docs to
v2URLs, notlatestredirects - Avoid deep wiki anchors — they change without notice
- Run link checker — tool or API
After renaming files, grep for old paths:
rg "authentication.md" docs/
Code samples that do not rot
The hardest docs-as-code problem: code samples that lie.
Patterns that work:
| Pattern | Example |
|---|---|
| Extract from real tests | <!-- test-snippet --> markers copied from CI |
| Versioned snippets | docs/snippets/v2/render.sh |
| Runnable in CI | npm run docs:check executes every bash block |
| Link to playground | "Try live" → API playground |
Anti-pattern: hardcoded API keys in samples. Use YOUR_API_KEY and document env vars.
Versioning documentation
Ship multiple doc versions when you support multiple API versions:
docs/
version-1.x/
version-2.x/
api/
render.md
Docusaurus has first-class versioning (docusaurus docs:version 2.0). Hugo uses separate content dirs or modules.
Add a version banner on older docs: "You're viewing v1.x docs. v2.x is current."
Search and discoverability
| Approach | Tradeoff |
|---|---|
| Algolia DocSearch | Free for OSS; index build required |
| Pagefind | Static, no external service |
| Built-in SSG search | Limited relevance |
| Google site: | site:docs.example.com — zero setup |
SEO metadata comes from frontmatter description + SSG meta templates. Run reading time to tag long guides.
Diagrams, math, and assets
Store assets in docs/static/ or docs/images/:

Mermaid in Markdown:
```mermaid
flowchart LR
PR --> CI --> Deploy
```
Build diagrams in browser, paste into repo. Audit math delimiters with math inventory.
Docs-as-code culture
Tools do not fix organizational drift. Practices that keep docs current:
- Definition of Done includes doc updates for user-facing changes.
- CODEOWNERS on
docs/routes PRs to technical writers. - Weekly doc debt sprint — fix broken links, update screenshots.
- Dogfood — internal teams use the same docs customers see.
- Changelog links — every release note links to updated doc pages.
Link releases to changelog and platform guides (Notion, Obsidian, VS Code) when audiences span tools.
API automation reference
| Task | Endpoint | Doc |
|---|---|---|
| Validate syntax | POST /api/v1/validate | docs |
| Render HTML preview | POST /api/v1/render | docs |
| Extract TOC JSON | POST /api/v1/extract/outline | docs |
| Check links | POST /api/v1/extract/links | docs |
| GFM audit | POST /api/v1/audit/gfm | docs |
| Format whitespace | POST /api/v1/format | docs |
Free tier: 100 requests/day — enough for small-team CI. Pricing.
Migration from wiki to docs-as-code
- Inventory — export all pages, count by section.
- Prioritize — migrate customer-facing pages first.
- Convert — HTML/Confluence/Notion → Markdown (HTML to Markdown guide).
- Redirect — old wiki URLs → new paths (301 map).
- Freeze wiki — read-only banner with link to new docs.
- Delete — archive wiki after analytics show traffic moved.
Expect 2–4 weeks for a 200-page wiki with one technical writer.
Common mistakes
1. Docs in a separate repo from code. Same-repo PRs keep docs in sync.
2. No CI on docs. Broken Markdown merges silently.
3. Auto-generated API docs only. Reference without narrative confuses beginners.
4. Screenshots as the only explanation. Alt text + prose for accessibility.
5. Ignoring mobile readers. Half of doc traffic is phones — test responsive theme.
6. Wikilinks in published docs. [[Page]] works in Obsidian, not on the web — use Markdown links.
Related articles
- VS Code Markdown guide — local authoring setup
- Markdown to HTML guide — render pipelines
- HTML to Markdown guide — wiki migration
- GitHub README guide — repo front page
- API quickstart — automate doc quality
Quick reference
| Practice | What it means |
|---|---|
docs/ in Git | Markdown source of truth |
| PR review | Same workflow as code changes |
| markdownlint | Style enforcement in CI |
| API validate | Syntax gate on every PR |
| extract/links | Broken URL detection |
| Docusaurus / Hugo | Static site deploy |
| frontmatter | title, description, sidebar metadata |
| relative links | ./page.md — not internal wiki URLs |
Docs-as-code is not a toolchain — it is a habit. Markdown in Git, checks in CI, deploy on merge. Start with ten pages and one workflow file; expand when the habit sticks.
Written by Markdown Viewer Team. Found this useful? Try the editor →
Keep reading
Hand-picked articles related to this one.
Convert Markdown to clean HTML for CMS, email, and static sites — browser tools, CLI, JavaScript libraries, static generators, and API pipelines compared with code examples.
Master GitLab Flavored Markdown — issues, merge requests, wikis, task lists, Mermaid, math, cross-references, alerts, and differences from GitHub GFM.
LLMs return Markdown that's usually right and occasionally broken — unbalanced fences, bad tables, skipped headings, dead links. Here's how to validate AI output programmatically before you trust it.