Docs as Code: What It Is and How to Set It Up
November 11, 2026 · 11 min read
Docs as Code: What It Is and How to Set It Up
Docs as code means writing documentation with the same tools and workflow as software. Pages are plain-text files in Git, changes go through pull requests, CI runs automated checks, and every merge rebuilds the site. This guide shows the exact files you need to set it up, plus when the approach isn't worth it.
What Is Docs as Code?
The Write the Docs guide describes it as a philosophy of writing documentation "with the same tools as code". Your docs get tracked in issues, stored in Git, reviewed like code and tested in CI. Writers work inside the product team's workflow instead of beside it.
A working setup rests on four pieces:
- Plain-text source in version control. Pages are Markdown, reStructuredText or AsciiDoc files in a Git repository, often the same one as the code.
- Review through pull requests. Every change goes through a branch and a pull request, where a writer and an engineer approve it.
- Automated checks. CI runs a Markdown linter, a prose linter and a link checker on each pull request.
- Automated publishing. Merging to the main branch builds the docs site and deploys it with no manual step.
You'll also see the name docs like code. It means the same thing, and it's the title of Anne Gentle's book Docs Like Code, which Write the Docs lists among its recommended reading.
Why Teams Move Documentation Into the Repository
The main reason is drift. When docs live in a wiki and code lives in Git, nothing forces them to change together. A renamed CLI flag ships on Tuesday and the wiki still shows the old one in March.
Putting docs in the repository lets one pull request update the feature and its page at the same time. Write the Docs points out a stronger benefit: you can block merging a feature until its documentation is included. You also get history for free. git log and git blame tell you who changed a sentence, when, and in which pull request.
| Question | Wiki or CMS | Docs in the repository |
|---|---|---|
| Where do docs live? | A separate tool with its own login | Markdown files next to the code |
| Who reviews a change? | Often nobody before it goes live | A writer and an engineer, in the pull request |
| How are errors caught? | Readers report them | CI checks formatting, style and links first |
| How does it publish? | Save button, live at once | Merge triggers a build and deploy |
The trade is speed for safety. A wiki edit goes live in seconds. A docs pull request waits for review and CI, which is slower but catches mistakes before readers see them.
What Does a Docs as Code Workflow Look Like?
A single change follows the same path every time:
- Create a branch from
main. - Edit or add
.mdfiles underdocs/. - Preview the page locally with your site generator.
- Open a pull request. The template fills in a checklist.
- CI runs the lint, style and link checks.
- A writer reviews clarity and an engineer reviews accuracy.
- Merge. A second workflow builds the site and deploys it.
Here's where the supporting files sit in a typical repository. Only the config and workflow files matter for this guide:
.
├── .github/
│ ├── CODEOWNERS
│ ├── pull_request_template.md
│ ├── styles/ # Vale packages and vocabulary
│ └── workflows/
│ └── docs.yml # lint, style and link checks
├── docs/ # your Markdown pages
├── .markdownlint.jsonc
└── .vale.ini
What goes inside docs/, such as folder layout and a page template, is covered in our guide to writing documentation in Markdown. For comments and doc comments inside the code itself, see our code documentation examples.
Reviewing Docs in Pull Requests
Review is where this approach earns its keep, and two small files make it consistent.
The first is a pull request template. Save it as .github/pull_request_template.md and GitHub pre-fills the description of every new pull request with it. A docs template works best as a task list the author ticks off before asking for review. Here's ours, which you can edit live:
In the preview, the checklist turns into checkboxes and the reviewer split becomes a table. Our editor displays the boxes as disabled; on GitHub, the author can tick them in the pull request description.
The second file is CODEOWNERS. It routes every docs change to the people who should approve it:
# Changes under docs/ request a review from the docs team
/docs/ @your-org/docs-team
# Writers also own the contributor guide
/CONTRIBUTING.md @your-org/docs-team
Per GitHub's CODEOWNERS documentation, the file can sit in .github/, the root or docs/, and GitHub uses the first one it finds in that order. Owners are requested automatically when a pull request touches their files, though not on drafts. The team needs write access to the repository. To make that approval mandatory, turn on "Require review from Code Owners" in your branch protection rule.
Automated Checks: Markdown Lint, Prose Style and Broken Links
Three checks catch most docs problems before a human reviewer sees them:
- markdownlint flags structural issues such as skipped heading levels, missing blank lines and bare URLs. Rules and config live in our markdownlint guide, so we won't repeat them here.
- Vale checks prose against a style guide: banned words, passive voice, spelling and product-name capitalization. The Vale docs list its config keys.
- lychee fetches every link in your Markdown files and reports the broken ones, including relative links to other pages.
Vale needs a .vale.ini at the repository root. This one pulls in the Google developer style package and stores it under .github/styles:
StylesPath = .github/styles
MinAlertLevel = warning
Packages = Google
[*.md]
BasedOnStyles = Vale, Google
Then one workflow runs all three on any pull request that touches docs. Save it as .github/workflows/docs.yml:
name: Docs checks
on:
pull_request:
paths:
- "docs/**"
- ".vale.ini"
- ".markdownlint.jsonc"
jobs:
markdownlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: DavidAnson/markdownlint-cli2-action@v25
with:
globs: "docs/**/*.md"
vale:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: vale-cli/vale-action@v3
with:
files: docs
links:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v7
- uses: lycheeverse/lychee-action@v2
with:
args: --no-progress './docs/**/*.md'
Each check is a separate job, so one failure doesn't hide the others. The markdownlint and lychee jobs fail the pull request when they find problems. The Vale action, by default, reports only on lines the pull request adds and doesn't fail the run. Add fail_on_error: true under its with: block to fail on error-level alerts once your team trusts the rules. If external sites make the link job flaky, add --offline to the lychee args to check only local links.
We prefer starting with just markdownlint and the link checker, then adding Vale once the team agrees on a style guide. A wall of prose warnings on day one teaches people to ignore the whole pipeline.
One catch from GitHub's workflow syntax docs: if you mark a path-filtered workflow as a required check, pull requests that skip it stay "Pending" and can't merge. Leave the docs checks optional, or drop the paths filter if you need them required.
To check a single page before you commit, paste it into the Markdown linter. It runs markdownlint in your browser, with toggles for line length, inline HTML, first-line heading and list marker rules.
Building and Publishing the Docs Site Automatically
Publishing is the last piece. A second workflow triggers on a push to main, runs your static site generator's build command and deploys the output to your host. Nobody uploads files by hand, so the live site always matches the main branch.
Many hosts can also build a preview for each pull request. Reviewers then read the rendered page instead of raw Markdown, which catches broken tables and misplaced images that a diff hides. Previews work best alongside the CI checks, not instead of them. GitLab's documentation team, for example, runs Vale in its CI/CD pipelines, where error-level rules fail the job.
The generator choice matters less than people think. MkDocs, Docusaurus and mdBook all read a folder of Markdown files; our MkDocs Markdown guide walks through one complete setup. If you ship several product versions, pick a generator that handles them. Docusaurus, for example, copies the current docs folder into a versioned snapshot when you run npm run docusaurus docs:version 1.1.0.
How Do You Handle Docs as Code With Non-Technical Contributors?
Support staff, product managers and subject-matter experts often know the answer but not Git. You don't need to teach them branching to get their edits.
On GitHub, anyone with an account can click the pencil icon on a Markdown file, edit it in the browser and choose Propose changes. If they don't have write access, GitHub forks the repository and opens the pull request for them. If they do, they can commit to a new branch and open a pull request, which lands in the same review flow. GitLab's Web IDE offers the same path: commit the change, then select Create MR.
For anything bigger than a typo, an issue template works better. The contributor describes what's wrong, and a writer turns it into a pull request. Writers keep ownership of merges, so quality stays consistent whoever reported the problem.
Some contributors prefer to draft a full page first. They can write it in our online Markdown editor, which is free and needs no account, with the live preview on the right. Then they download the .md file or copy the text and paste it into GitHub's web editor. The editor has no Git connection, so that commit step is always theirs.
When Docs as Code Isn't the Right Fit
The approach is a good default for software documentation, not a universal one. It struggles in a few situations:
- Contributors who won't touch Git. Web editors help with small fixes, but a team of writers who live in Word will fight the workflow every day.
- Review bottlenecks. If two writers must approve every change from 40 engineers, pull requests queue up and docs fall behind.
- Heavy reuse and conditional content. Markdown has no built-in way to share one warning across 200 pages or show a paragraph only to one product tier. Generators add some include features, but a component content management system handles this natively.
- Print-first or regulated output. Manuals that need strict page layout, translation memory or signed approval trails usually need tooling that a static site generator lacks.
The honest limitation is the learning curve. Expect the first month to be slower than the old wiki while people learn branches, reviews and failing checks.
Docs as Code FAQ
Docs as code works best when you start small. Put the Markdown in the repository, add a pull request template and a CODEOWNERS line, then switch on markdownlint and a link checker. Add Vale and preview builds once the habit sticks. To draft or check a page before you commit it, write it in the editor and run it through the Markdown linter.