Skip to content
All posts
8 min read
markdown
documentation
devops
guide
api

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:

  1. Author edits docs/api/authentication.md on a branch.
  2. Opens PR — teammate reviews prose and code samples together.
  3. CI runs Markdown lint, link check, and spell check.
  4. Merge → static site deploys to docs.example.com in ~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

PropertyMarkdownProprietary wiki
Git diffsClean line changesExport blobs or N/A
Tool choiceHugo, Docusaurus, MkDocs, AstroVendor lock-in
Offline / backupgit cloneExport hacks
CI validationLint, link check, API auditLimited
Engineer familiarityREADMEs already MarkdownLearning curve
PortabilityObsidian, VS Code, any editorMigration 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

SSGBest forMarkdown flavor
DocusaurusProduct docs with versioningMDX + GFM
HugoSpeed, large sitesGoldmark GFM
MkDocs MaterialInternal tech docsPython-Markdown + extensions
Astro StarlightModern docs + performanceMDX
Next.jsDocs inside app monorepoMDX remote
GitBook (Git sync)Less ops, hostedGFM

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
---
FieldPurpose
titlePage H1 and <title> tag
descriptionSEO meta and social cards
sidebar_positionNav order (Docusaurus)
slugOverride URL path
draft: trueHide 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)

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

Broken links destroy trust. Rules:

  1. Prefer relative links inside the repo: [auth](./authentication.md)
  2. Version external links — pin docs to v2 URLs, not latest redirects
  3. Avoid deep wiki anchors — they change without notice
  4. 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:

PatternExample
Extract from real tests<!-- test-snippet --> markers copied from CI
Versioned snippetsdocs/snippets/v2/render.sh
Runnable in CInpm 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

ApproachTradeoff
Algolia DocSearchFree for OSS; index build required
PagefindStatic, no external service
Built-in SSG searchLimited 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/:

![Architecture](./images/render-pipeline.png)

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:

  1. Definition of Done includes doc updates for user-facing changes.
  2. CODEOWNERS on docs/ routes PRs to technical writers.
  3. Weekly doc debt sprint — fix broken links, update screenshots.
  4. Dogfood — internal teams use the same docs customers see.
  5. 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

TaskEndpointDoc
Validate syntaxPOST /api/v1/validatedocs
Render HTML previewPOST /api/v1/renderdocs
Extract TOC JSONPOST /api/v1/extract/outlinedocs
Check linksPOST /api/v1/extract/linksdocs
GFM auditPOST /api/v1/audit/gfmdocs
Format whitespacePOST /api/v1/formatdocs

Free tier: 100 requests/day — enough for small-team CI. Pricing.

Migration from wiki to docs-as-code

  1. Inventory — export all pages, count by section.
  2. Prioritize — migrate customer-facing pages first.
  3. Convert — HTML/Confluence/Notion → Markdown (HTML to Markdown guide).
  4. Redirect — old wiki URLs → new paths (301 map).
  5. Freeze wiki — read-only banner with link to new docs.
  6. 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.

Quick reference

PracticeWhat it means
docs/ in GitMarkdown source of truth
PR reviewSame workflow as code changes
markdownlintStyle enforcement in CI
API validateSyntax gate on every PR
extract/linksBroken URL detection
Docusaurus / HugoStatic site deploy
frontmattertitle, 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.