June 6, 2026

Writing in MDX

A starter guide — how posts work, what MDX shortcodes are available, and how to add your own content.

This journal splits two moods: a brutalist bento home and an editorial reading experience for posts. The home grid is loud with structure; the articles are calm with words.

Stack at a glance

Click each card to read what it does in this project:

File-based routing under app/[locale]/, static generation for posts, and server components for the bento home grid.

Project shape

Expand folders to explore the layout:

globals.css — design tokens

*.mdx — articles + postMeta

bento/ — home grid

mdx/ — interactive article blocks

lib/posts.ts — scans content/posts/

messages/ — UI translations (en, zh)

i18n/ — locale routing

Step-by-step

Drop a .mdx file in content/posts/. Export a postMeta object with title, date, description, and optional tags. The slug comes from the filename — hello-world.mdx becomes /notes/hello-world.

Try it yourself

Here is the shape of a new post:

content/posts/my-post.mdx

export const postMeta = {
title: "My first note",
date: "2026-06-06",
description: "A short summary for listings and SEO.",
tags: ["journal"],
};

Your MDX content starts here.

Then run the dev server:

Terminal

pnpm dev

Visit /en/notes/my-post to see it live.

Images in MDX

Place images in public/ and reference them with standard markdown syntax. The global MdxImg component adds a subtle border and spacing:

Gallery hero

The same asset powers the image carousel on the home bento grid.

Tags and discovery

Tags are optional strings on each post's postMeta. They power filter pills on the notes index, clickable tags on article headers, and the tag carousel on the home grid.

Try the filter below — it uses real posts from this site:

Try filtering by tag

The black gapdesign, bento, css, rwd
Building this journalguide, nextjs, mdx, build
Writing in MDXguide, mdx, journal
On makingcraft, process, design
Hello, worldjournal, intro

Bento gaps (interactive demo)

The home grid uses a single CSS token for black lines between tiles. Drag the slider to see how gap size changes the feel:

Adjust the gap

CSS variable: --spacing-bento-gap: 8px

Mini bento preview

What is next

Browse the full notes index, read Hello, world for the site's tone, then replace this file with your own writing.

The best journals are built in small steps — one post, one tag, one quiet page at a time.