# How to write posts

There are two ways to add a post — pick whichever fits the post.

Single file

For text-only posts, drop a .md file directly in content/posts/:

content/posts/
  my-quick-thought.md

The slug is the filename without the extension.

Bundled folder

When the post needs assets (images, attachments), give it a folder with an index.md:

content/posts/
  my-illustrated-essay/
    index.md
    attachments/
      diagram.png

The slug is the folder name. This layout is Obsidian-friendly:

• keep images in attachments/
• plain relative paths like ![diagram](attachments/diagram.png) work
• Obsidian embeds like ![[diagram.png]] also work and are rewritten to static URLs automatically
• bundled assets are synced into public/post-assets/ before dev, build, and start
• if you add or rename attachments while the dev server is already running, rerun npm run sync:assets

Frontmatter

Every post starts with YAML frontmatter:

---
title: "The post title"
date: "2026-04-22"
description: "Optional one-liner shown in lists and meta tags."
category: "infra/pxe/ubuntu"
tags: ["one", "two"]
draft: false
---

Only title is strictly required — everything else has sensible defaults. draft: true posts are visible in next dev but hidden in next build. A post can have at most one category path (shown as @category), and nested categories are written with /, for example infra/pxe/ubuntu. Parent category pages include posts from their child categories too. tags is a list (shown as #tag).

Scaffold one quickly

$ npm run new -- "My next post"
$ npm run new -- "An illustrated post" --bundle