Headless Documentation: Git as CMS, one-click publishing, machine-ready content

From a heavyweight CMS to Git as the source of truth

At Intel, documentation ran on a docs-as-code setup paired with Adobe Experience Manager and a CI/CD pipeline. It worked, but publishing was heavy: content lived partly in the CMS, releases were coupled to it, and every change carried more process than the content itself warranted.

The goal was to make Git the single source of truth: author in Markdown, treat docs like code, and publish to a lightweight static site with one click, so ContentOps stopped being a bottleneck and writers could ship without waiting on the CMS.

ContentOps, working across the org

I worked mainly on ContentOps for the migration, partnering with system architects, developers, and product managers and owners to move authoring and publishing onto GitHub as a headless CMS with one-click publishing.

A working reference implementation I own

To make the pattern concrete, defensible, and independent of any employer’s internal systems, I built a small open-source reference implementation from scratch in 2026. It is real code that runs, not a diagram.

One note on timeline, for accuracy: the headless CMS and one-click publishing above was my Intel engagement. The Model Context Protocol layer below is my own later prototype, built after that engagement and after MCP existed. It extends the same headless pattern to a new audience; it does not describe anything shipped at Intel.

Documentation lives as Markdown with frontmatter in Git. A GitHub Actions workflow publishes it to a static site with one click or on merge. The same Markdown is served to AI agents over the Model Context Protocol, so an agent queries structured content instead of scraping a rendered page.

What this is, without the jargon

A short version for anyone who does not work with documentation tooling day to day.

Documentation is normally written for people to read in a browser. AI assistants, like the ones built into modern coding tools, increasingly need that same information too. They work far better when it is handed to them as clean, structured data than when they have to read a web page and guess.

This project keeps one copy of the documentation, written as plain text files in GitHub, the place software teams already store their code. From that single copy, two things happen automatically: a normal website is published for people, and a small program (the "MCP server") makes the exact same content available to an AI assistant whenever it asks. Change the text once, and both the website and the AI stay in sync.

MCP, the Model Context Protocol, is simply an open standard for how an AI assistant asks an outside source for information. Here it lets the assistant look things up in the real documentation instead of inventing an answer. The payoff: no duplicated effort, no separate system to maintain, and AI that answers from your actual docs.

Connect an AI assistant to it yourself

The prototype is open source and runs locally. With Node.js and an MCP-capable client such as Claude Desktop, you can point an assistant at these docs in a couple of minutes.

{
  "mcpServers": {
    "headless-docs": {
      "command": "node",
      "args": ["/absolute/path/to/headless-docs-mcp/src/server.mjs"]
    }
  }
}

Prefer to just look? The published docs site and its machine-readable index are linked at the top of this page. The site is what a person sees; the MCP server serves the same content to an agent.

One source, two audiences

Treat documentation as code and you get one source of truth. Deliver it headlessly and the same content can serve both human readers and the AI agents that are becoming a second audience.

What this project demonstrates

1. 1ContentOps is an architecture problem as much as a writing one: repo layout, frontmatter, and the review workflow decide whether a headless setup scales.
2. 2Making Git the single source of truth removes a whole class of drift between a CMS and the repository.
3. 3The same structured content that publishes cleanly for humans is what an AI agent needs to answer without hallucinating.
4. 4A small working prototype you own and can run is the most defensible way to show a pattern you have led professionally.