All articles
MDX3 min read

This blog runs on MDX — and writing a post takes one file

No CMS, no database, no admin panel. A markdown file in a git repo, and this article exists.

by Vidhal Elame

This very article is a file called writing-in-mdx.mdx sitting in a folder of my repository. I wrote it in my code editor, saved, pushed, and it appeared here with its date, its reading time and its typography. That's the whole publishing pipeline.

How it works

Each post starts with a small header (the frontmatter):

---
title: "My next article"
date: "2026-07-10"
tag: "Notes"
description: "One sentence that sells the click."
---

Below it, plain markdown: headings, lists, links, code. Because it's MDX and not just markdown, I can also drop React components right in the middle of prose when an idea needs more than text.

What the site does by itself

I only write the text. The rest is worked out from the file:

  • the article's address comes from the file name: writing-in-mdx.mdx becomes /blog/writing-in-mdx;
  • the reading time is counted from the text, at 200 words a minute;
  • the order of the list follows the date in the header, newest first;
  • the blog's filters come from the tag field: a new topic creates its own filter;
  • the cover is drawn by the site when the article has no picture, from what it is about.

That last point spares me the chore that kills blogs: making a picture for every post. A hackathon post gets a race bib with its place. A series episode gets a poster with its number. This one gets a drawing of a file turning into a page.

Two languages, two files

The site exists in French and English. So each article has two files with the same name:

content/blog/writing-in-mdx.mdx        the English version, with the date and the topic
content/blog/fr/writing-in-mdx.mdx     the French version: title, summary and text

The date and the topic are written once, in the English file. The French file only restates what gets translated. If the French version is missing, the site shows the English one rather than an empty page.

Components in the middle of the text

This is where MDX parts ways with markdown. In my self-hosting series, some passages called for a diagram: the path of a request, the anatomy of a domain name. Rather than exporting pictures, I wrote React components, and I call them in the article like a tag.

The diagram then follows the light or dark theme, stays sharp at every size, and gets fixed like code. An exported picture has to be redone on every change.

There is a limit to respect: one component per idea that truly needs it. An article stuffed with widgets becomes an application, and nobody reads it any more.

Why I like it

  • Versioned like code: every edit is a git commit, typos have a history;
  • No admin panel to secure, no database to back up;
  • The editor I already live in is the writing tool;
  • Pages ready in advance: articles are built once, at deploy time, and served as they are. Nothing to compute when someone arrives.

What it costs

This system is not for everyone, and it is better to say so.

  • You need to know git. For a developer that is a plus. For anyone else it is a wall.
  • No one-click preview from a phone: I write on my computer, check the result locally, then push.
  • No scheduled publishing. An article is live when it is pushed, not before.
  • Pictures are yours to file in the repository.

For a personal blog run by a developer, these constraints weigh almost nothing. For an editorial team, a real CMS is still the right choice.

Writing the next one

My path to a new article is four moves: create the file, fill in the header, write, push.

If you're a developer thinking about writing more: remove every excuse between you and publishing. Mine is now a single file.