Docs-as-Code Is Now the Standard for Knowledge Distribution

Markdown files in a git repo are not a documentation system. They are the beginning of one.

The format is not the system. What makes it a system is what you build around it — the write path that gets knowledge in, the read path that gets it out, the agent-readable layer that makes it accessible without a browser, and the MCP interface that delivers it at the point of work.

This is about that full stack. Not as a product. As a pattern.

But first: why every platform you’ve already tried has failed.

Why Confluence, SharePoint, Highspot, and Notion all fail the same way

65–70% of company-produced content goes unused by the people it was built for. Not because the content is bad. Because the distribution mechanism is wrong.

The pattern is consistent across every knowledge management platform. Someone discovers a better way to do something. They write a wiki page, a Confluence doc, a Highspot card, a Notion database entry. They share the link once. The link gets buried in a channel. Three months later the knowledge is stale and the person who wrote it has moved on. The institutional memory is gone.

This is not a content quality problem. It is a passive distribution problem.

Every major knowledge platform is built on the same assumption: write the knowledge down, put it somewhere organized, and people will find it when they need it. This assumption is empirically false. The activation energy required to leave whatever you’re doing, navigate to the knowledge base, run a search, evaluate the results, and read a document is too high relative to asking a colleague or accepting ignorance.

Confluence adds structure. SharePoint adds permissions. Highspot adds analytics. Notion adds flexibility. None of them solve the activation energy problem because they’re all optimizing the container, not the delivery mechanism. The knowledge still sits waiting to be found.

The staleness problem compounds this. Passive documentation rots because:

• The author has no incentive to maintain it after initial creation
• Readers have no mechanism to signal that content is outdated
• There is no feedback loop from the people using the knowledge back to the people who wrote it
• The content becomes increasingly misaligned with current reality — and confidently wrong is worse than silent

The platforms treat knowledge as a distribution problem: how do we get content to more people? The actual problem is retrieval: how do we make the right knowledge available at the moment someone needs it, without requiring them to go looking for it?

Those are different problems. They require different architectures.

Why docs-as-code

The premise is simple: treat your knowledge the way engineers treat code. Markdown as source. Git as version control. Pull requests as the review gate. Build process as the publishing step.

The benefits are well-documented. Portability — markdown files survive platform migrations. Diffability — every change is reviewable and reversible. Contribution model — any engineer can contribute using the same tools they use for code. No CMS login. No proprietary format. No export-import cycle.

But the deeper reason is control — and specifically, the ability to build multiple read paths on top of a single source.

When your knowledge lives in Confluence, it renders as Confluence pages. When it lives in Highspot, it renders as Highspot cards. The platform controls the rendering, the search, the access model, and the API surface. The moment you want to do something the platform doesn’t support — feed content to a vector database, serve it via MCP, expose it to an agent — you’re exporting, transforming, and re-importing. Every step adds drift between source and derived surface.

With docs-as-code, the markdown is canonical. The website is a render. The vector index is a render. The MCP server is a delivery layer on top of a render. You can have all three simultaneously, from the same source files, updated atomically when a file changes.

Full control is not about distrust. It’s about the ability to build the retrieval architecture that actually solves the problem — delivery at the point of work, not content sitting in a container waiting to be found.

The bigger shift: AI closed both paths

Docs-as-code originated in engineering. Software teams adopted it because it solved a real problem: documentation needed to live next to code, change with code, and be reviewed like code. The tooling — git, markdown, CI/CD — was already there. The pattern spread from API docs to developer portals to internal runbooks to system design documents.

For a decade, it stayed mostly in engineering. GTM teams used Confluence. Sales teams used Highspot. Operations used SharePoint. The pattern didn’t cross the boundary because the friction was too high. Writing markdown, opening a pull request, navigating a review pipeline — these require familiarity with git workflows that most non-engineers don’t have. The knowledge platform vendors knew this and competed on editor experience, not architecture.

2025 changed the equation. AI closed both paths simultaneously — and that’s a different kind of shift than friction reduction.

The write path. Contributing to a markdown repo no longer requires knowing git. An agent drafts the content, enforces the structure, opens the pull request, and shows you the result. You review and approve. The contribution model that required git fluency now requires only judgment — which is the part that was always valuable anyway. Fern and Mintlify have documented this as a flywheel: the same AI tools that help engineers write code now help everyone else write the knowledge artifacts that surround it.

The read path. MCP and llms.txt mean knowledge is no longer something you go looking for. It is delivered to the point of work — inside the coding tool, the agent session, the research workflow. The activation energy problem that killed every passive knowledge platform dissolves when retrieval is built into the tool someone is already using. There are now over 2,400 MCP servers in public directories; more than 200 are in the knowledge base and documentation category. MCP is becoming the API layer for knowledge, the same way REST became the API layer for data.

This is already crossing team boundaries. GTM engineers — a hybrid role that’s emerged in the last two years — are building docs-as-code workflows for battlecards, playbooks, and account intelligence. Sales and RevOps teams are querying knowledge bases via MCP without writing a line of code. a16z has named docs-as-code tooling (Cursor, Mintlify, Context7) as foundational to what they call the trillion-dollar AI software development stack.

But will GTM teams actually make the shift?

This is the harder question — and the honest one.

The architecture argument is easy to win. Docs-as-code is clearly better: portable, diffable, multi-surface, owned. Anyone who’s spent time thinking about knowledge distribution reaches the same conclusion. The question is not whether it’s better. The question is whether teams will move.

The inertia is real. Confluence is in every IT procurement catalog. Highspot has multi-year enterprise contracts and deep Salesforce integrations. SharePoint is bundled into Microsoft 365 licenses that companies are already paying for. Switching means training, migration, and a change management project that nobody on the team has budget or time for. Most knowledge workers have never touched git and don’t plan to start.

But the inertia argument assumes the old friction — and the old friction is what’s gone.

The reason GTM teams didn’t adopt docs-as-code before was not that the architecture was wrong. It was that the contribution model required skills they didn’t have. Opening a pull request, resolving merge conflicts, understanding directory structure — these were the actual blockers, not ideological resistance to markdown.

AI removed those blockers. You don’t need to open a pull request. An agent does it. You don’t need to know where the file lives. The agent knows. You don’t need to format the frontmatter correctly. The skill enforces it. The entire surface that separated “people who contribute to git repos” from “people who don’t” has collapsed into a single interaction: review and approve.

The switching cost is also lower than it looks. You don’t migrate Confluence. You start a new repo alongside it, put the content that matters most in there first, and let the old platform rot on its own timeline. The first team that gets answers at the point of work — while everyone else is still opening browser tabs — becomes the proof of concept. That’s how these shifts happen: not through IT mandates, but through teams that move faster than the ones still on the old stack.

The inertia is real. But inertia is a force, not a wall. The question is whether the pull is strong enough to overcome it. For the first time, the pull is coming from the tools people are already using — the AI coding tools, the agent workflows, the MCP clients that are becoming the default interface for knowledge work. That’s a different kind of pull than “here’s a better architecture.” It’s “here’s where the knowledge is already flowing.”

The write path

The write path is where knowledge enters the system. Get this wrong and you get a wiki that three people contribute to and four hundred people ignore.

A good write path has three properties:

Low friction for contributors. The bar to submit should be lower than the bar to publish. If contributing requires understanding the full site structure, running a local build, and navigating a review process, most people won’t bother. They’ll send a Slack message instead and the knowledge will die there.

A review gate proportional to the content type. Not all content needs the same bar. A correction to an outdated pricing figure needs a lighter touch than a new strategic positioning page. The write path should distinguish between these and route accordingly.

Structured input that produces structured output. Freeform contributions produce freeform content. If you want your knowledge base to have consistent frontmatter, consistent section structure, and consistent voice, the write path needs to enforce that — not rely on contributors to read a style guide.

In practice, this means two paths:

The direct path — edit a markdown file, open an MR, a maintainer reviews and merges. This works well for small corrections, updates to existing pages, and contributions from people who know the repo. It’s the git workflow engineers already understand.

The mediated path — a skill or agent drafts the content on behalf of the contributor, enforces the structure, runs the quality checks, and submits via an API. The contributor sees the draft and approves before anything enters the pipeline. This works for people who have knowledge worth sharing but won’t open a git MR.

The mediated path is where MCP comes in — but more on that below.

The read path

The read path is the browser surface. A static site built from the markdown files, with navigation, search, and a structure that matches how people think about the knowledge domain.

The choices here matter more than they seem.

Structure is navigation. The directory hierarchy of your content becomes the sidebar of your site. A flat structure produces a flat site — everything at one level, no sense of relationship between topics. A well-nested structure lets someone land on a section page and immediately understand what’s here and how it relates to adjacent topics.

Search is the primary interface. Most people don’t browse a knowledge base. They search. The search implementation needs to be fast, tolerant of partial queries, and able to surface the right page even when the query doesn’t match the title exactly. Full-text search (FlexSearch, Lunr) handles the common case well. For a domain with a lot of jargon and synonyms, vector search handles the gaps.

Freshness signals matter. A knowledge base where you can’t tell if a page is six weeks old or eighteen months old is a liability. Every page should carry a last-updated date and an owner. Not as decoration — as a contract. The owner is responsible for keeping that page current.

Chunking strategy

This is where most docs-as-code implementations leave value on the table.

If you’re only building a browser site, chunking doesn’t matter — the full page renders in the browser. But the moment you want to feed your content to an LLM, power a vector search index, or serve it via a retrieval-augmented system, chunking becomes the thing that determines retrieval quality.

The unit of retrieval should be the unit of meaning. A chunk that contains half a section and the beginning of the next section is worse than a chunk that contains one complete section. The goal is for each chunk to be independently useful — something a language model can read and cite without needing the surrounding context to make sense of it.

In practice, this means structuring your markdown deliberately:

• H2 sections as retrieval units. Each major section should be self-contained — a complete thought with a clear topic. If a section requires reading the section before it to make sense, split the background into the section or make it standalone.
• Front matter as metadata. title, description, last_updated, page_owner, tags — these aren’t decoration. They’re the structured metadata that lets a retrieval system filter, rank, and cite correctly. A description field that accurately summarizes the page is worth more than a perfectly written introduction.
• No orphaned context. Tables, code blocks, and lists embedded inside a section should make sense without the surrounding paragraph. If a table requires reading two paragraphs above it to interpret, the table is not a good retrieval unit.
• Explicit rather than implicit. “See above” and “as mentioned earlier” are death in a chunked retrieval system. The chunk has no above. Write each section so it can stand alone.

The chunking strategy is set at write time, not at index time. The chunking configuration in your vector database (chunk size, overlap, boundary detection) is the last resort, not the first line of defense. Well-structured markdown with natural section boundaries produces better chunks than any chunking algorithm applied to poorly-structured content. LangChain’s MarkdownHeaderTextSplitter is the canonical starting point — it chunks by header hierarchy, which maps directly to well-structured docs.

Multiple LLM surfaces: llms.txt and beyond

A website built for humans has a secondary audience now: AI agents. And the standard HTML-to-context conversion pipeline that agents use to read websites is lossy.

HTML carries navigation chrome, footer links, cookie banners, JavaScript-rendered content, and layout structure — none of which an agent needs. The conversion from DOM to useful text is expensive and unreliable. Different agents handle it differently, and the results vary.

llms.txt addresses this directly. A Markdown file at your site’s root — /llms.txt — that gives AI systems a curated, structured map of what’s here and where to find it. Machine-readable, human-authored. Think of it as a sitemap optimized for inference rather than crawling. Anthropic, Vercel, and LangGraph all publish one.

But llms.txt is just the entry point. A full agent-readable content layer has multiple surfaces:

/llms.txt — the index. A flat list of pages with one-line descriptions and direct URLs. An agent that needs to find a page on a topic can load this file and make an informed decision about which URL to fetch next, without crawling the full site.

/llms-full.txt — the full content dump. All pages concatenated in markdown, for agents that want to load the entire knowledge base in one request. Useful when the agent needs broad coverage rather than targeted retrieval. Heavy but complete.

Section-level llms files — /claude-code/llms.txt, /bedrock/llms.txt. For large knowledge bases, section-level indexes let an agent load only the relevant slice rather than the full index.

Raw markdown endpoints — serving the source markdown directly at a predictable URL gives agents the cleanest possible content. No HTML parsing. No conversion loss. Just the markdown, exactly as it was written.

The principle across all of these: reduce the distance between what was written and what the agent reads. Every transformation step introduces noise. The agent-readable layer minimizes those steps.

MCP: the read layer

llms.txt and raw markdown endpoints handle passive consumption — an agent that loads a URL and processes what it finds. MCP (Model Context Protocol) handles active retrieval — an agent that asks a question and gets a ranked answer.

An MCP server sitting in front of your knowledge base exposes a search tool. The agent calls it with a natural language query. The server retrieves semantically relevant chunks from the vector index, reranks them by relevance, applies a confidence threshold, and returns ranked results with citations.

The difference from a browser search:

• Semantic matching. “What are the cost implications of running agents at scale?” returns the inference economics page even if that page doesn’t contain those exact words.
• Point-of-work delivery. The agent calls the tool mid-conversation, without switching context to a browser. The knowledge arrives where the thinking is happening.
• Citation by default. Results include source page, section, and confidence score. The agent can cite rather than hallucinate.
• Confidence gating. A low-confidence result can be flagged rather than returned confidently. Knowing when you don’t know is as valuable as knowing when you do.

The MCP server is the highest-fidelity surface for AI consumption. It requires the most infrastructure (vector database, Lambda or container, auth layer) but produces the best retrieval experience. For a knowledge base where agents are the primary consumers, it’s the right investment.

Extending MCP for write

Read is half the problem. The other half is getting knowledge into the system.

The contribution pipeline via MCP closes the loop. The same agent that queries the knowledge base can also submit to it — without leaving the conversation, without opening a browser, without knowing where the files live in the repo.

A submit tool on the MCP server takes a content object (type, title, body, metadata) and routes it through the write pipeline:

submit tool call
    ↓
validation (structure check, required fields, quality bar)
    ↓
staging (DynamoDB DRAFT table or equivalent)
    ↓
dispatcher (async Lambda or queue worker)
    ↓
pull request (targeted at the right path in the repo)
    ↓
maintainer review → merge → live

The contributor never touches the repo. The draft is created by an agent — possibly the same coding tool the contributor is already using — following the structure and voice guidelines enforced by a skill or system prompt. The contributor sees the draft, approves it, and the pipeline handles the rest.

A list_my_submissions tool closes the feedback loop: the contributor can check the status of their submission, see if the MR is open, and know when it merged.

This is the pattern that makes a knowledge base self-sustaining. The people closest to the knowledge — who generated it in conversations, in prototypes, in field calls — can contribute it without changing tools or learning a new workflow. The knowledge that would otherwise die in a Slack thread has a path to permanence.

The full stack

Put it together and the architecture looks like this:

WRITE PATH
    Direct MR (engineers, maintainers)
    MCP submit tool → staging → dispatcher → MR (everyone else)
            ↓
    Git repo (markdown — single source of truth)
            ↓
BUILD
    Static site generator (Hugo, Astro, etc.)
    Vector index sync (chunked, embedded)
    llms.txt generation
            ↓
READ PATH
    Browser site (humans)
    /llms.txt + /llms-full.txt (passive agent consumption)
    MCP search tool (active agent retrieval)

Each layer is independently replaceable. The static site generator can change without touching the markdown. The vector database can change without touching the site. The MCP server can change without touching either.

The markdown is the only thing that can’t change — because it’s the source of truth for everything else. That’s the constraint that makes the whole system coherent.

Where to start

Not all of this needs to exist on day one. The layers have a natural build order:

1. Markdown + git + static site. Zero infrastructure. The content is owned, the site is live, and contributions via MR are possible. This is the foundation.

2. llms.txt. One file. Hugo and Astro can generate it automatically from the content index. Costs nothing, makes the site immediately more useful to agents.

3. MCP search. Requires a vector database and a Lambda or container. This is the first infrastructure investment — worth it once the content base is stable and agents are a real consumer.

4. MCP write. Requires a staging layer and a dispatcher. Build this when the contribution volume justifies it — when the friction of the direct MR path is the actual bottleneck on knowledge growth.

The mistake is building all four layers before validating the content. A perfectly instrumented retrieval system on top of 20 pages of inconsistently structured content is worse than a static site with 200 well-structured pages. The content quality determines the retrieval quality. Start with the content.

The inertia question is real. But inertia describes the present, not the trajectory. The teams that move first don’t do it because they read a post about docs-as-code architecture. They do it because their AI tools already work better when the knowledge is in markdown — and once you’ve felt that, going back to a wiki that agents can’t read feels like a step backward.

The format was always markdown. The infrastructure around it is finally good enough for everyone.