All articles
November 20, 2026

What Is Docs-as-Code? A Plain-English Guide

what-is-docs-as-code-cover.png

With DocStar, docs-as-code means your API docs live in your Git repository next to the code, change in the same pull request, and publish automatically on every push to your docs site, your MCP server and your CLI. And with the DocStar MCP connected, your AI coding agent sets the whole thing up from one prompt.

Docs-as-code is a way of writing documentation with the same tools and workflow you use for software: docs are plain-text files (Markdown, OpenAPI) stored in version control, changed through commits and pull requests, reviewed like code, and published automatically by a pipeline instead of copied into a separate tool by hand.

This guide explains how docs-as-code works, why it matters more now that AI agents read and call your API, and how to run it in DocStar with your AI agent doing most of the work.

#

How docs-as-code works

The idea is simple: treat docs like source code. In practice that means four things.

Practice Traditional docs Docs-as-code
Where docs live A separate docs tool or wiki Text files in the same repo as the code
How they change Someone edits them later, by hand In the same commit and pull request as the code change
How they are reviewed Rarely, after publishing In the PR diff, before merge
How they are published Copy, paste, import, click publish A CI pipeline publishes on push

The formats are usually Markdown for guides and OpenAPI (YAML or JSON) for API reference. If OpenAPI is new to you, our plain-English guide to OpenAPI covers it.

#

Why docs-as-code matters more in the age of AI agents

API docs go stale. A developer renames a field or adds a parameter, and the docs get updated later, by someone else, or never.

That used to mean a confused human reader. Today it means a broken agent. In DocStar, the same API docs feed four things:

  • your public docs site,

  • llms.txt and Markdown copies of every page that AI tools read,

  • the MCP server AI assistants use to call your API, and

  • the CLI generated from your published API docs.

So when the docs are wrong, an agent calls your API with the wrong field and the call fails. Keeping docs next to the code, and changing them in the same pull request, is the most practical way to stop that. It is the same reason teams now keep agent instructions in the repo, as we explain in What Is AGENTS.md?

#

How docs-as-code works in DocStar: GitHub Sync

DocStar's docs-as-code feature is GitHub Sync. It keeps a DocStar collection in sync with your GitHub repository:

  • OpenAPI files go in api-docs/. A folder is a module, and a file on its own is a one-file module.

  • Markdown pages go in docs/. A folder is a section, with its own page.md.

  • On every push, a GitHub Action sends the changed files to DocStar. Your docs site, MCP tools and CLI commands update with no manual import or copy-paste.

  • docstar.md tells your coding agent the rules. It holds the folder structure and which endpoints to document (only the ones your users call, never private or admin ones). One line in AGENTS.md, CLAUDE.md or .github/copilot-instructions.md tells the agent to follow it whenever an endpoint is added, changed, renamed or removed, and to update api-docs/ in the same change.

You can use one folder or both. Full details are in the GitHub Sync help guide.

That gives you the three things docs-as-code promises:

  1. Updating docs is part of the code change. The agent edits the endpoint's spec in the same commit as the code.

  2. Publishing is automatic. Push, and the Action publishes the changed files.

  3. Docs are reviewed like code. Spec changes show up in the pull request diff, where your reviewers already are.

#

Let your AI agent set it up in one prompt

Set up by hand, GitHub Sync is about six steps: find the collection ID, write the OpenAPI files, create an API token, add it as a GitHub secret, download the workflow, and add docstar.md. Most people stop partway. With DocStar, you don't have to do any of them yourself.

#

Step 1: Connect your coding agent to the DocStar MCP

Add DocStar to Claude Code, Cursor, Codex or another assistant, either from its connector directory or as a custom MCP server with this URL:

https://mcp.docstar.io/mcp

The first time the agent needs your workspace, you sign in to DocStar in your browser. There is no API key to copy, and the agent works only with the workspaces and collections your account can access. See Connect Your AI Assistant.

#

Step 2: Give it one prompt

Open your repository in the agent and paste:

Set up DocStar GitHub Sync for this repo. Read my latest code, not an old spec, and write an OpenAPI file in api-docs/ for every endpoint my users call. Never add admin, internal or service-to-service routes. Add docstar.md and the line in AGENTS.md, store the DocStar API token as a GitHub secret without showing it to me, add the workflow, and give me the MCP URL when the first sync is done. Show me your plan and ask before changing anything.

#

Step 3: What the agent does

With the DocStar MCP connected, the agent:

  • creates the collection (or uses the one you name),

  • reads your routes and writes the OpenAPI files from the code,

  • generates the API token and saves it as the DOCSTAR_API_KEY GitHub secret without printing it in chat,

  • downloads the workflow into .github/workflows/ and adds docstar.md plus the instruction line,

  • commits, pushes, and hands back your MCP server URL after the first sync.

It asks before it changes anything, and new endpoints stay drafts unless they are marked published (each operation needs x-docstar-published: true to go live).

[Screenshot: Coding agent showing its GitHub Sync plan before making changes]

#

Step 4: Your part: review and judgment calls

The agent does the typing. You make the calls only a person should make:

  • What stays private. api-docs/ becomes public documentation. Check that no admin route, internal hostname or secret slipped in.

  • Naming and tone. Endpoint names and descriptions are what humans and AI assistants read first.

  • What goes live. Review the first pull request and the drafts in DocStar, then publish.

If you're moving existing docs from another tool first, see How to Migrate Your Docs to DocStar with Your AI Agent.

#

Keep it current

Once GitHub Sync is in place, keeping docs current is part of normal coding. Ask your agent for a change as usual:

Add a currency field to the create-payment endpoint, and update its spec in api-docs/ in the same change.

Because of the line in AGENTS.md, the agent updates the OpenAPI file alongside the code even when you forget to ask. Your reviewer sees the spec change in the PR diff, you merge, and the Action publishes it. The docs site, the MCP tools and the CLI all pick up the new field.

Be clear about the limit. GitHub Sync works when the agent, or a developer, actually updates the spec. If someone changes code without an agent, or the agent skips the docstar.md rule, the docs can drift and nothing catches it automatically. DocStar does not watch your repo or compare code with docs. Docs-as-code makes the right habit easy; it doesn't replace it. For more habits that help, read How to Keep Your API Docs in Sync with Your Code.

#

Docs-as-code vs a docs editor: do you have to choose?

Not with DocStar. Docs-as-code suits API reference and developer guides that change with the code. Help articles, FAQs and changelogs are often written by support, product or marketing people who prefer a visual editor.

DocStar gives you both in one workspace: GitHub Sync for the collections that live in your repo, and a real-time collaborative block editor for the ones your writers own. Everything shares the same domain, branding, search and AI features, so readers never see the seam.

#

Prefer to set it up yourself?

You can. The GitHub Sync guide has four steps: add the workflow with one curl command, download docstar.md and add the instruction line, create an API token and save it as the DOCSTAR_API_KEY repository secret, then commit and push. Every push that changes api-docs/ or docs/ then syncs to your collection, and you can follow each run in the repository's Actions tab.

#

Why teams choose DocStar for docs-as-code

  • One source, four outputs. The same specs power your docs site, llms.txt and Markdown copies, a hosted MCP server and a CLI.

  • Agent-first setup. One prompt replaces six manual steps, and the token never appears in chat.

  • Safe by default. New endpoints arrive as drafts, and docstar.md tells agents never to document private or admin APIs.

  • Writers welcome too. Collections your writers own use the collaborative editor, in the same workspace.

  • All in one place. API docs, help docs, FAQs, changelog and blog on your own domain and brand.

#

FAQ

#

What is docs-as-code in simple terms?

It means writing documentation as text files in your code repository, changing it through pull requests, and publishing it automatically. With DocStar, those files sync to your docs site, MCP server and CLI on every push.

#

Which formats does DocStar GitHub Sync support?

OpenAPI files in an api-docs/ folder for API reference, and Markdown files in a docs/ folder for pages and guides. You can use one folder or both.

#

Do I need to write OpenAPI files by hand?

No. With the DocStar MCP connected, your coding agent reads your latest code and writes the OpenAPI files for you. You review them in the pull request.

#

Does DocStar detect when my docs drift from my code?

No. DocStar publishes what you push. Drift is prevented by updating the spec in the same change, which docstar.md and the line in AGENTS.md tell your coding agent to do.

#

Will new endpoints go live straight away?

Only if they are marked x-docstar-published: true. Otherwise they arrive in DocStar as drafts for you to review.

#

Get started free

Put your docs next to your code and let your AI agent do the setup. Connect the DocStar MCP, paste the prompt above, and review the first pull request. Get started free.

docs as codeGitHub SyncOpenAPIAPI documentationAI agentsAGENTS.md