Masala Geek
← notes
sprout

The CMS for the agentic era is a folder of Markdown files

Content management built for agents starts with files they can read, edit, diff, validate, and publish without translating everything through a dashboard.

· #ai#agents#publishing#local-first

The content management system I use most now does not look like a CMS.

It is a folder of Markdown files.

There is no rich-text dashboard between the agent and the content. Research, drafts, notes, publishing metadata, and finished articles live beside one another as files. Git records what changed. A static-site build turns the approved files into the public website.

This sounds deliberately primitive. For agent-assisted work, it is often the more capable architecture.

Traditional CMS interfaces were designed around human hands

Most content-management systems assume a person will log in, open a form, fill in fields, choose media from a library, preview a page, and press publish.

That interface is useful for people. It is an unnecessary translation layer for an agent.

An agent already knows how to:

Put the content behind a dashboard and the agent needs an API, credentials, a browser automation path, or a custom integration to reach it. Put the content in files and the normal development environment becomes the content API.

The important difference is not Markdown versus rich text. It is whether content is directly addressable inside the agent’s working environment.

A Markdown file can carry both meaning and workflow

A useful content file is not an unstructured text dump. It has a small contract.

---
title: "The CMS for the agentic era"
date: 2026-08-31
status: sprout
tags: ["ai", "agents", "publishing"]
---

The article starts here.

The body carries the idea. The frontmatter carries the fields the publishing system needs. A schema can verify the date, status, title, tags, and optional source URL before the site builds.

That gives both humans and agents a predictable interface:

The file is portable. It can be opened in a code editor, Obsidian, a terminal, a Git web interface, or a purpose-built editor later. The source does not depend on the interface used to edit it.

Git becomes the editorial history

A traditional CMS usually has its own revision system, roles, preview state, and publishing log.

With file-based content, much of that can be expressed through the workflow the team already uses:

This does not mean every writer should learn advanced Git commands. It means the source can use Git even if a friendlier interface sits above it.

The distinction matters. Git can be the durable content history without becoming the only human editing experience.

Files make agent workflows composable

Once content is available as files, the workflow stops being trapped inside one application.

An agent can take a rough capture and create a research note. It can compare that note with existing articles, identify overlap, propose a stronger angle, draft the website version, derive a LinkedIn adaptation, and prepare image metadata. Each stage leaves an artifact that another agent or a future session can inspect.

capture
  → research.md
  → article.md
  → content.json
  → image.png
  → website build
  → social distribution

The handoffs are visible. If the social caption makes a claim that does not appear in the research, the gap can be inspected. If an article changes after approval, Git shows the difference. If a model is replaced, the content does not need to be exported from the old model’s memory.

Markdown is not valuable because agents love a particular file extension. It is valuable because the artifacts remain inspectable outside the agent that created them.

The website becomes a renderer, not the source of truth

This changes how I think about a personal website.

The website is not where the content lives. It is one rendering of the content.

The same Markdown source can become:

That is why I keep Markdown as the source and treat HTML as a review or delivery layer. Humans benefit from visual hierarchy, responsive layout, diagrams, and interaction. Agents benefit from source that is easy to search, edit, and diff. One format does not need to do both jobs.

The static-site generator sits between them. It turns the content contract into the public experience.

Where “just use Markdown” breaks down

A folder of files is not a complete answer for every team.

Several problems return as soon as more people become involved:

Non-technical editing. A marketing or editorial team may need a familiar document interface rather than a repository checkout.

Permissions. Git repository access is often broader than the per-document or per-field permissions available in a mature CMS.

Media management. Images, video transformations, alt text, crops, and CDN delivery need more than a Markdown convention at scale.

Approvals and scheduling. A pull request can model review, but embargoes, timed publication, localization, and multi-channel scheduling may need dedicated workflow services.

Structured relationships. Large catalogs and deeply relational content may be more natural in a database with a content API.

Concurrent editing. Git handles mergeable text well, but it is not a pleasant collaborative writing interface for everyone.

The answer is not to pretend these needs disappear. It is to separate the durable source from the interfaces around it.

A team might edit content through a friendly web interface that commits validated Markdown behind the scenes. Media might live in object storage while files contain stable references. Scheduling might remain in a distribution tool. Search might use a generated index.

The agent-native part is that the canonical content remains readable and operable as files.

What an agent-native CMS should optimise for

If I were designing a CMS for agent-assisted publishing, I would start with these properties:

  1. Direct file access. Agents can read and edit content without browser automation.
  2. Explicit schemas. Metadata and content types are validated deterministically.
  3. Versioned history. Every change can be reviewed, attributed, and reversed.
  4. Portable source. Content can move between tools without a proprietary export project.
  5. Local execution. Drafting, search, link checks, and builds can run close to the files.
  6. Human review surfaces. People can review prose, diffs, previews, and visual structure in the form best suited to each decision.
  7. Separation of source and distribution. Publishing to a website or social platform does not become the only copy of the work.
  8. Bounded agent permissions. Drafting, approval, and publication remain distinct capabilities.

Markdown and Git satisfy much of that foundation. They do not solve the entire editorial experience, but they give it a durable center.

The boring stack becomes more useful

My current site is intentionally plain: Markdown, Astro, Git, and a small set of conventions.

That used to look like a minimalist publishing stack. With coding agents, it starts to look more like infrastructure.

An agent can understand the whole path from an idea to the published page because the path is made of artifacts it can inspect. There is no hidden content state inside a dashboard and no separate knowledge base that silently drifts away from the public version.

The CMS for the agentic era may still have a beautiful editor, a media library, roles, scheduling, and previews.

But underneath, I increasingly want it to behave like a folder of Markdown files.