Markdown, MDX or headless CMS: how to choose

Every content website has to answer one question before it grows: where will the text live and who will edit it? The most common answers today are three: Markdown files, MDX files or a headless CMS.

There is no universal winner. Each option trades simplicity for power, or editorial team autonomy for more parts to maintain. This article compares the three based on the official documentation of each technology and of Astro, consulted on October 8, 2026.

Markdown: plain text in files

Markdown is a text format with light markup. A # at the start of a line becomes a heading, asterisks become emphasis, a dash becomes a list item. The file remains readable even without being converted into a page.

Because many variations emerged over the years, a common specification was created, CommonMark, whose latest listed version is 0.31.2, from January 2024. Many tools also adopt GitHub’s variant, GFM (GitHub Flavored Markdown).

Astro, for example, reads Markdown without installing anything. The Markdown in Astro page states that support is built in, that GFM is enabled by default and that you can add plugins to transform the text. Each file can have frontmatter, a block at the top with data such as title, date and author.

Strengths:

• Portability. It is plain text. It moves between tools, frameworks or hosting without complicated conversion.
• Version control. The files live in the Git repository, with a history of every change and review via pull request.
• Small error surface. There is no code to execute inside the text.

Limitations:

• Writers have to deal with files. For journalists or marketing teams unfamiliar with Git, this is a real barrier.
• Limited expressiveness. An interactive chart or a custom callout block does not fit in plain Markdown. It has to be handled in the page template or through conventions.

MDX: Markdown with components

MDX is, in the words of its official documentation, “a format that combines Markdown with JSX”. JSX is the syntax used in React and other libraries to write interface components that look like HTML. In MDX, you can import a component and place it in the middle of the text, as well as use JavaScript expressions between curly braces.

In Astro, MDX is not built in. It requires the @astrojs/mdx integration. With it, an .mdx file can import Astro components and components from other libraries, and export variables.

The gain is clear: an article can have a calculator, a chart or a standardized alert block in the middle of the text, without hacks.

The cost shows up on three fronts.

Less forgiving syntax. The same page notes that Markdown “forgives” mistakes, while JavaScript breaks on a typo. MDX also has differences: indented code does not work, raw HTML is replaced by JSX, and the < and { characters need to be escaped when they appear in the text. A stray less-than sign can bring down the build.

Security. MDX’s Getting started guide is blunt. It says MDX is a language compiled to JavaScript and that, therefore, it is safe if you trust the authors and unsafe if you do not. The literal recommendation is not to let “random people from the internet” write MDX. In practice, reader comments or texts from outside contributors should not become MDX without controls.

Coupling. An MDX article depends on the components it imports. If a component is renamed or the site changes framework, the text has to be revisited. The content stops being just content.

Headless CMS: content in a separate service

A CMS (content management system) is the software in which the team writes, reviews and organizes content. A headless CMS does only that part and does not generate the pages. Astro’s CMS documentation explains that, since Astro handles presentation, a headless CMS is the recommended fit: it stores the content, and the site fetches that data to build the pages, either through a ready-made integration or through the CMS’s own library.

According to the same page, a CMS usually offers a visual editor, standardized content types and collaboration tools. It works well for structured content, such as posts with a rich text editor or product sheets with required fields.

There are two broad models:

• API-based CMS. The content lives in the service’s database, and the site fetches it over the internet.
• Git-based CMS. The visual editor writes files to the repository itself. This is the case of Decap CMS, which describes itself as an open-source React app, under the MIT license, that wraps the Git workflow. When someone saves in the editor, the change becomes a commit in the repository, without them having to learn Git.

The Git-based model is a middle ground: the team gets a visual interface, and the content stays in files, often Markdown.

The cost of a headless CMS:

• One more part. There is an account, a service, permissions and, in many cases, a subscription to maintain. If the service goes down or changes its pricing, the site feels it.
• Integration. The site needs code to fetch and validate the data. In Astro, this is done with loaders in content collections, which accept remote data, such as data from a CMS.
• A new build for every change, on a static site. If pages are generated at build time, a correction in the CMS only appears after a new build. The same documentation describes “live” collections, which fetch data on each request, but they do not support MDX.

Side-by-side comparison

Criterion	Markdown	MDX	Headless CMS
Who writes comfortably	Technical people or those used to files	Technical people	Anyone with access to the editor
Where content lives	Git repository	Git repository	CMS service (or Git, for Git-based CMSs)
Components in the middle of the text	No	Yes	Depends on the CMS and the integration
Security risk in content	Low	High if authors are not trusted	Depends on the CMS’s access control
Portability	High	Medium (depends on components)	Depends on the service’s export
Extra parts to maintain	None	MDX integration	Service, integration and build trigger

The risk and portability cells are the newsroom’s assessment, based on the characteristics described in the sources, not measurements.

How to decide

A few questions help you choose.

Who will write? If the team is technical and small, Markdown in the repository is usually enough. If there are editors unfamiliar with Git, a CMS, API-based or Git-based, tends to avoid bottlenecks.

Does the text need components? If few articles need something interactive, you can handle it in the page template, with frontmatter fields. If many do, MDX starts to pay off, as long as the authors are trusted.

How often does the content change? On a static site, every change requires a build. If changes are daily and made by several people, plan how the build will be triggered.

How much do you want to depend on third parties? Files in the repository do not depend on any external service to exist. An API-based CMS does.

The options can also be combined. It is common to have Markdown for most texts, MDX for a few special pages and a Git-based CMS as an interface for people who do not code.

Documented case: the Token & Tech website

The Token & Tech website uses the first option, and this can be verified in the code. Article texts are .md files, one per language, and each article’s data, such as category, topics and sources, lives in separate YAML files. Astro’s content collections read these files with the glob() loader and validate them against a schema at build time. The project does not install the MDX integration or use a CMS.

This describes the current configuration, not a general recommendation. The collections are detailed in Astro Content Collections.

Key takeaways

• Markdown is the simplest and most portable foundation: plain text, versioned with the code, with little that can go wrong.
• MDX adds components to the text, but it is code: less forgiving syntax and use restricted to trusted authors.
• A headless CMS opens the site to non-technical teams, at the cost of one more service, an integration and, on static sites, a build per change.
• Decide based on who writes, how often content changes and how much you are willing to depend on third parties. Combining options is common.