Da Nang, VN,--:--:--
All articles
  • #mdx
  • #next.js

How this blog works: writing posts with MDX

A tour of every authoring feature on this blog — frontmatter, code blocks with line highlights, callouts, tables and custom React components.

NDNgoc Duc2 min read

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:

content/blog/en/my-post.mdx
yaml
---
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
  1. Write the post
  2. Preview it with pnpm dev
  3. 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.

components/Counter.tsx
tsx
"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:

OptionExampleWhat 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
css
: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:

mdx
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 ✦

Got a project in mind?

Let's talk