Every article here is a single .mdx file in content/blog/<lang>/. The filename becomes the URL, so this post lives at content/blog/en/writing-with-mdx.mdx → /en/blog/writing-with-mdx. Drop a new file in that folder, run the build, and it shows up on the blog index, on the home page and in the prev/next links.
Two languages
English posts live in content/blog/en/, Vietnamese ones in content/blog/vi/ — same filename. If a post has no Vietnamese version yet, /vi shows the English one with an EN badge and a short notice, so you can translate gradually.
Frontmatter
Each file starts with a YAML block. Only title and date are really required:
---
title: "My new post"
description: "One sentence that shows up in lists and link previews."
date: "2026-11-21"
tags: ["react", "css"]
draft: true # hide it until it's ready
---Posts are sorted by date (newest first). Reading time and the "On this page" table of contents are generated automatically from the content.
Markdown you already know
Regular bold, italic, strikethrough, links and inline code all work. So do lists:
- GitHub-flavored markdown via
remark-gfm - Heading anchors via
rehype-slug— hover a heading and click the# - Syntax highlighting via
rehype-pretty-code+ Shiki
- Write the post
- Preview it with
pnpm dev - Ship it
Good writing is rewriting — and good code is mostly deleting.
Code blocks
Fenced code gets highlighted at build time, so there's zero JavaScript cost for readers. It follows the light/dark theme automatically and has a copy button.
"use client";
import { useState } from "react";
export function Counter() {
const [count, setCount] = useState(0);
return (
<button onClick={() => setCount((c) => c + 1)}>
Clicked {count} times
</button>
);
}That block uses three meta options after the language:
| Option | Example | What it does |
|---|---|---|
title="…" | title="app.tsx" | Adds a filename header |
{lines} | {4,8-10} | Highlights lines |
showLineNumbers | — | Shows a line-number gutter |
/word/ | /useState/ | Highlights a word |
:root {
--primary: #34a0a4;
}Callouts
Because it's MDX, you can use React components right inside the text. Callout is available globally — no import needed:
Your own components
Need something interactive just for one post? Import it at the top of the .mdx file like any React component:
import { Chart } from "@/app/components/blog/Chart";
Here's the data:
<Chart data={[1, 3, 2, 5]} />Server components render to plain HTML at build time. Add "use client" to a component only when it needs state or browser APIs.
That's everything. Happy writing ✦