Docs as code hit a wall - what comes next

Documentation-as-code (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. Trouble starts when your documentation needs outgrow that original use case.

Non-engineers need to contribute. Content must be reused across 3 products. A single topic must publish differently for administrators and end users. Markdown and Git have no answer to any of it. These are not edge cases. They are the normal requirements of a documentation team that has moved past a single-product developer audience.

This article maps where docs as code stops working. It reads the Material for MkDocs maintenance-mode announcement as an ecosystem signal. Then it covers what comes next for teams already at 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 one toolchain. Markdown files in a Git repository, built by a static site generator (MkDocs, Hugo, Docusaurus, Jekyll), deployed to a hosting platform. That toolchain is not the philosophy. As The Doc Landscape points out, there are 2 versions of docs as code in circulation. The narrow one: write in plain text, use Git, work like an engineer. The broad one: bring structure, rigor, and shared ownership to documentation.

Most teams implement the narrow version. The narrow version is what breaks.

5 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. These 5 matter most.

1. Content reuse does not exist in standard Markdown

A security disclaimer that appears in 40 topics across 3 products is not one disclaimer. Markdown gives you one tool for the job: copy and paste. When the legal team updates the wording, you update 40 places. Miss a page and you ship inconsistent content.

Static site generators like Hugo, MkDocs, and Docusaurus bolt on include directives (readfile shortcodes, snippets extensions, MDX imports). Every implementation is proprietary. None of them track where a reused block appears. You cannot answer "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. Past 50 topics, this stops being a nice-to-have. It separates confident editing from 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 2 options. Maintain 2 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 reinvents the same wheel, poorly. That is content management, built inside 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 editor shows one thing. The published page shows another. Review and QA get 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 PDF or lean on tools like WeasyPrint or Pandoc. Those need separate configuration and careful testing. The result is usually a second build pipeline. It drifts out of sync with the web output. Teams maintain 2 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. The complaint is earned. 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."

A non-developer contributor must learn all of this to make a single documentation edit:

1. Cloning a repository
2. Creating a branch
3. Understanding the staging area
4. Writing a commit message
5. Pushing to a remote
6. Opening a pull request
7. Resolving merge conflicts

That is 7 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. Then they ask the tech writing team to transfer the content. The promise of docs as code was shared ownership of documentation. The reality is 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. Thousands of documentation sites depended on it. Donath explained that MkDocs itself had deeply rooted architectural limitations. A theme layer could not overcome them.

This is not an argument against Zensical, which looks promising. It is an observation about ecosystem fragility. Your documentation toolchain depends on a static site generator. The generator depends on a theme. The theme depends on a solo maintainer's sponsorware revenue. That is a dependency stack. Any engineering team would flag it in application code.

Material for MkDocs had a good outcome (a planned transition with a successor). Most open-source documentation tools do not get that.

The State of Docs Report 2025 backs this up. Most teams do not stop at choosing a static site generator. They build on top of it: custom plugins for navigation, custom scripts for content reuse, custom CI pipelines for publishing. Every custom piece 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 (1 to 3 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. You write 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. Those tools required XML expertise, six-figure contracts, and months of implementation. They were inaccessible to the 2 to 15 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. It requires no XML and no dedicated infrastructure team. The main 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. Subject matter experts and product managers contribute directly.
• Version control that does not require Git expertise. Built-in versioning, or Git sync that runs in the background. Writers stay in a visual interface.

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

How to evaluate whether you have outgrown docs as code

Answer these 5 questions honestly. If 3 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 designed for a different scale. If the list sounds familiar, here is why I built a tool to address them.