Docs as code hit a wall. Here is what comes next.

Documentation-as-code, the practice of writing docs in Markdown, storing them in Git, and publishing through a static site generator, is one of the most influential ideas in technical writing over the past decade. For developer documentation maintained by engineers, it works well. The problems start when your documentation needs outgrow that original use case.

When non-engineers need to contribute, when you need to reuse the same content across three products, when a single topic must publish differently for administrators and end users, Markdown and Git do not have answers. These are not edge cases. They are the normal requirements of a documentation team that has moved beyond a single-product developer audience.

This article breaks down where docs as code stops working, what the Material for MkDocs maintenance-mode announcement tells us about the ecosystem, and what the next step looks like for teams that have hit the wall.

What docs as code actually is (and is not)

Docs as code is a workflow philosophy: treat documentation with the same rigor as source code. Use plain-text formats. Store content in version control. Review changes through pull requests. Automate publishing through CI/CD. The Write the Docs community defines it as writing documentation "with the same tools as code."

In practice, "docs as code" has narrowed to mean a specific toolchain: Markdown files in a Git repository, built by a static site generator like MkDocs, Hugo, Docusaurus, or Jekyll, and deployed to a hosting platform. That toolchain is not the philosophy. As The Doc Landscape points out, there are two versions of docs as code in circulation: the narrow one (write in plain text, use Git, work like an engineer) and the broad one (bring structure, rigor, and shared ownership to documentation). The narrow version is what most teams implement. And the narrow version is what breaks.

Five capabilities Markdown and Git cannot provide

The limitations of docs as code are not vague feelings of friction. They are specific, structural gaps in what Markdown and Git can do. Here are the five that matter most.

1. Content reuse does not exist in standard Markdown

If you maintain a security disclaimer that appears in 40 topics across three products, Markdown gives you one option: copy and paste. When the legal team updates the wording, you update it in 40 places, or you miss some and ship inconsistent content.

Some static site generators bolt on include directives (Hugo's readfile shortcode, MkDocs' snippets extension, Docusaurus MDX imports), but every implementation is proprietary and none of them track where a reused block appears. You cannot answer the question "which pages use this component?" without grep.

In a CCMS, a reusable component is a first-class object with where-used tracking. Edit it once, and every reference updates. Before you change it, you can see the blast radius. This is not a nice-to-have feature for teams managing more than 50 topics. It is the difference between confident editing and guesswork.

2. Conditional content requires custom tooling that Markdown does not support

Your documentation serves administrators and end users. Administrators need CLI instructions and configuration file details. End users need GUI steps and screenshots. In docs as code, you have two options: maintain two separate sets of files (doubling your maintenance burden) or build a custom filtering system on top of Markdown.

Neither option is good. Separate files drift apart. Custom filtering systems become internal projects that someone must maintain, test, and document. Markdown has no native concept of conditional blocks, audience tags, or publish-time filtering. Every docs-as-code team that needs conditional output ends up reinventing the same wheel, poorly, because they are building content management features in a system designed for static text files.

3. Variables are hacked in, not built in

Product names change. Version numbers increment. API endpoints move between environments. In structured authoring, you define a variable once and reference it everywhere. Update the value, and every instance updates at publish time.

In Markdown, variables do not exist. Teams work around this with templating engines (Liquid, Jinja2, Nunjucks), static site generator shortcodes, or find-and-replace scripts. Even developer docs platforms like Mintlify only offer per-import snippet props — not global variable sets. Each workaround introduces a build dependency and a failure mode. None of them let a writer see the resolved value while editing. The content in the editor and the content on the published page look different, which makes review and QA harder.

4. Multi-channel output is an afterthought

Your developer portal is a website. Your compliance team needs a PDF. Your partner integrations team needs a Markdown export for their own documentation system. Docs-as-code toolchains are designed for one output: a static website.

PDF generation from Markdown is notoriously difficult. Most static site generators either do not support it or rely on tools like WeasyPrint or Pandoc that require separate configuration, custom CSS, and careful testing. The result is usually a second build pipeline that drifts out of sync with the web output. Teams end up maintaining two publishing systems for one set of content.

5. Git is a barrier for non-developer contributors

This is the limitation that generates the most community discussion, and for good reason. Sarah Moir's widely shared article "Docs as code is a broken promise" identifies Git complexity as the core problem: "To do docs as code, writers need to learn how to use and troubleshoot Git. Git is not simple."

The list of concepts a non-developer contributor must learn to make a single documentation edit in a docs-as-code workflow: cloning a repository, creating a branch, understanding the staging area, writing a commit message, pushing to a remote, opening a pull request, resolving merge conflicts. That is seven steps before the content review even begins.

In practice, subject matter experts and product managers avoid the process entirely. They send corrections over Slack, file tickets, or write in Google Docs and ask the tech writing team to transfer the content. The promise of docs as code was shared ownership of documentation. The reality, in many organizations, is that Git creates a bottleneck at the writing team.

The Material for MkDocs signal

In November 2025, Martin Donath announced that Material for MkDocs was entering maintenance mode. Version 9.7.0 would be the last feature release. All previously paid Insiders features were folded into the free edition. The sponsorware model was discontinued. Future development would focus on Zensical, a new static site generator built from scratch in Rust.

Material for MkDocs was not a small project. It was the most popular documentation theme in the Python ecosystem, with thousands of documentation sites depending on it. Donath explained that MkDocs itself had deeply rooted architectural limitations that could not be overcome through a theme layer.

This is not an argument against Zensical, which looks promising. It is an observation about ecosystem fragility. When your documentation toolchain depends on a static site generator, which depends on a theme, which depends on a solo maintainer's sponsorware revenue, you are stacking dependencies in a way that would concern any engineering team if it were application code. Material for MkDocs had a good outcome (a planned transition with a successor). Many open-source documentation tools do not get that.

The State of Docs Report 2025 backs this up. That means most teams are not just choosing a static site generator. They are building custom tooling on top of it: custom plugins for navigation, custom scripts for content reuse, custom CI pipelines for publishing. Each of those custom pieces is a maintenance liability.

When docs as code is still the right choice

Docs as code is not universally broken. It remains the right approach when:

• Your audience is developers and your contributors are engineers who already use Git daily.
• Your content is single-audience and does not need conditional filtering or multi-channel output.
• Your documentation is one product, one version, one language and content reuse is not a requirement.
• Your team is small (one to three writers) and the overhead of a content management system is not justified.

What comes after docs as code

The step after docs-as-code is not a step backward to wikis or Word documents. It is a step forward to structured authoring: writing content as reusable, semantic building blocks that can be assembled, filtered, and published in multiple formats.

Structured authoring has existed for decades in the form of DITA XML and enterprise CCMS platforms. The problem was that those tools required XML expertise, six-figure contracts, and months of implementation. They were inaccessible to the two-to-fifteen-person documentation teams that make up most of the market. The research on what 59 technical writers actually say about XML confirms this: 78% say XML is unnecessary for their work.

A component content management system brings the capabilities that docs as code lacks (content reuse, conditional publishing, variables, multi-channel output) without requiring XML or a dedicated infrastructure team. The key features to evaluate:

• Component reuse with where-used tracking. Write a block of content once. Insert it anywhere. See every location it appears before you edit it.
• Conditional content at publish time. Tag blocks by audience, platform, or product tier. Filter at publish time so a single source produces multiple outputs.
• Variable sets. Define product names, version numbers, and URLs as variables. Switch between variable sets for different product lines or environments.
• Visual editing for all contributors. A block editor that does not require Markdown syntax or Git knowledge, so subject matter experts and product managers can contribute directly.
• Version control that does not require Git expertise. Built-in versioning, or Git sync that runs in the background while writers work in a visual interface.

That last point matters. The best outcome is not abandoning version control. It is keeping the benefits of version control (change history, branching, rollback) while removing the requirement that every contributor learn Git. GitBook tried this with bidirectional Git sync, but without the structured authoring layer (reuse, conditions, variables), you hit the other four limitations.

How to evaluate whether you have outgrown docs as code

Answer these five questions honestly. If three or more answers are yes, your team has likely outgrown a docs-as-code workflow.

1. Do you copy-paste the same content into multiple files? If yes, you need content reuse.
2. Do non-engineers avoid contributing to documentation? If yes, your toolchain is creating a bottleneck.
3. Do you maintain separate files for different audiences? If yes, you need conditional publishing.
4. Do you manually update version numbers or product names across files? If yes, you need variables.
5. Do you spend more time maintaining your toolchain than writing content? If yes, your documentation infrastructure has become a project of its own.

None of these are judgments about your team's skill. They are symptoms of a toolchain that was designed for a different scale. If the list sounds familiar, here is why I built a tool to address them.

FAQ

Is docs as code the same as docs-like-code?

The two terms are used interchangeably. "Docs-like-code" was popularized by Anne Gentle's book of the same name and emphasizes treating documentation with code-like rigor. "Docs as code" is the more common phrasing in the Write the Docs community. Both refer to the same workflow: plain text, version control, automated publishing.

Can I keep my Git history if I move to a CCMS?

It depends on the system. Some CCMS platforms offer Git sync, which means your content is stored in a visual editor but changes are committed to a Git repository in the background. This preserves your change history and lets developers continue working in their preferred tools while writers use a visual editor. Not all CCMS platforms offer this, so check before committing to a migration.

How long does it take to migrate from docs as code to a CCMS?

For a documentation set of 50 to 200 topics, expect two to four weeks. The bulk of the time goes to restructuring content for reuse (identifying shared blocks, creating components, setting up conditions) rather than the technical import itself. Most CCMS platforms can import Markdown directly. If you are migrating from MadCap Flare specifically, see the step-by-step migration guide.

What is the difference between a CCMS and a help authoring tool?

A help authoring tool (HAT) like MadCap Flare or RoboHelp produces documentation output from a desktop application. A CCMS adds component-level reuse, multi-author workflows, and publish-time assembly. Think of a HAT as a powerful word processor for documentation. A CCMS is a content management system where the unit of content is a reusable component, not a page.

Does structured authoring require XML?

No. Structured authoring originated with SGML and DITA XML, but modern CCMS platforms use block editors that store content as structured data without exposing XML to writers. The underlying principles (reusable components, semantic structure, conditional publishing) do not depend on any particular markup language.