What is docs-as-code?
Docs-as-code explained: documentation written in plain text, kept in Git beside the code, reviewed in pull requests and published automatically.
By Gusenga Thierry ·
The short answer
Docs-as-code is writing documentation with the same tools and workflow as software: plain-text files such as Markdown, kept in version control next to the code, changed through pull requests and review, and published automatically when changes merge. The result is that docs can change in the same commit as the behaviour they describe.
The short answer
Docs-as-code treats documentation as part of the codebase instead of a separate wiki. Pages are text files in Git. They are written in the same editor, changed on the same branches, reviewed in the same pull requests and published by the same kind of automation as the code. The term is used widely in technical writing; the practice matters more than the name.
What it involves
- Plain-text formats. Markdown most often, sometimes reStructuredText or AsciiDoc. Diffs are readable and no tool owns the content.
- Version control. Every change has an author, a date and a reason, and docs can be branched and tagged with releases.
- Review. A pull request that changes behaviour can be required to update the docs, and reviewers see both at once.
- Automated checks. Broken links, missing titles and spelling are caught in CI before anything is published.
- Automated publishing. A merge to the main branch updates the live site.
Why teams adopt it
Documentation goes wrong when it drifts from the product. Keeping it beside the code shortens the distance between the change and the page that describes it. It also removes a separate tool and login for engineers, gives docs the same history and rollback as code, and makes the docs easy to move: they are just files.
What it costs
It assumes writers are comfortable with Git. Product managers, support staff and technical writers who are not may find the workflow slower than a wiki. Review can become a bottleneck. And publishing needs a pipeline that someone owns.
Common tools
| Tool | How it publishes | Notes |
|---|---|---|
| Docusaurus | Builds a static React site | Rich plugins and MDX; you host the output |
| MkDocs | Builds a static site from Markdown | Simple configuration; Material theme is popular |
| Sphinx | Builds HTML, PDF and more | Strong for Python and long technical manuals |
| Jekyll or Hugo with GitHub Pages | Builds on push | Free hosting; public unless on GitHub Enterprise Cloud |
| DocuGate | Reads Markdown from GitHub on request, no build | Folders become navigation; access control per space |
Getting started
- Create a
docs/folder in the repository and move existing pages into it as Markdown. - Add an
index.mdas the landing page and group pages into folders. - Add a check to CI, for example a link checker.
- Require docs changes in the pull request template for user-facing changes.
- Connect a publisher so a merge updates the site.
DocuGate is one publisher for that last step. It reads the docs folder on
the branch you choose: folders become sidebar groups, the first # heading
becomes the title, and a push invalidates the cache so the next request
reads the new commit. The docugate CLI's check command catches broken
links before they are published. Each space can be public or gated; see
access control.
Questions people also ask
Is docs-as-code only for developer documentation?
No. Handbooks, runbooks, policies and partner guides work the same way. The limit is the writers: people who never use Git need a way to edit that does not ask them to learn it.
Do I need a static site generator for docs-as-code?
Not necessarily. Generators such as Docusaurus or MkDocs are the common route, but some platforms read the markdown straight from the repository and render it without a build.
Markdown, reStructuredText or AsciiDoc?
Markdown is the most widely known and is supported almost everywhere. reStructuredText, used by Sphinx, and AsciiDoc handle cross-references and long technical books better. Pick the one your writers will actually use.
Where should the docs live, in the code repository or a separate one?
In the code repository when the docs describe that code, so a change and its documentation share one pull request. A separate repository suits docs that span several products or are written by a different team.
Read next
- How to turn markdown files into a documentation website: The ways to publish a folder of markdown as a docs site: a static site generator, a hosted docs platform, or a host that reads the repository directly.
- Shipping a docs site without a sidebar config file: How DocuGate builds navigation from the folders, headings and index files already in a repository, and the one optional file for what folders cannot say.
- How do I password protect a Docusaurus site?: Docusaurus has no login of its own. The four ways to put a password or sign-in in front of a Docusaurus site, and what each one costs.
- How to publish private documentation from a GitHub repo: Turn the markdown in a private GitHub repository into a docs site only the right people can read, without a second permission list to maintain.
Get started with DocuGate, free.