Writing Posts & Thoughts

Garden organizes content into posts (content/posts/) and thoughts (content/thoughts/). Both are UTF-8 Markdown files whose filenames contain only lowercase letters, digits, and hyphens (a-z, 0-9, -).

1.Post Front Matter (content/posts/*.md)

Create a post with make new DIR=systems SLUG=wal-checkpoint TITLE="Understanding WAL | Checkpoints and Recovery" or create a .md file directly:

---
title: Understanding WAL | Checkpoints and Recovery
date: 2026-10-18
updated: 2026-10-19
description: How write-ahead logging preserves snapshot visibility under concurrent reads and writes, and how background checkpoints bound log growth.
tags:
  - Database
  - Storage
pinned: false
draft: false
cover: windowsill-herbs.svg
original: https://example.com/original-post
references:
  - title: SQLite Write-Ahead Logging
    url: https://www.sqlite.org/wal.html
  - title: Database Internals
---

At the bottom of every post page, between the Webmention section and the comments, sit the Previous and Next navigation cards. Posts link only to other posts ordered by date (where Previous is the older post), while column entries follow their order in content/columns.yaml; the oldest and newest entries show only one card.

Caution

Do not write a slug field in Front Matter (npx garden check reports an unexpected-slug error because the filename is already the slug). Posts do not use a topic field either.

2.Code Blocks and the Diff Toggle

Standard code blocks show their language label (such as RUST, TS, PYTHON, or SHELL) and a copy button in the top-right corner. To show how a snippet changed from an earlier version, place the updated code block first and follow it with a garden idea fence stating what changed in one sentence:

```go
func openStore(path string) (*Store, error) {
	return openWithMode(path, ModeWAL)
}
```

```garden
Compared with the previous version: open the store with ModeWAL instead of ModeJournal.
```

Following the garden-ui skill, the Agent runs npx garden ui apply to replace that idea fence with a diff fence right below the code block (see Writing with AI). The page combines the two adjacent blocks into a single code frame with tabs for the full code and the diff against the previous version, while the copy button always copies the new full code:

func openStore(path string) (*Store, error) {
	return openWithMode(path, ModeWAL)
}

 func openStore(path string) (*Store, error) {−	return openWithMode(path, ModeJournal) (removed)+	return openWithMode(path, ModeWAL) (added) }

Hand-written format: Without an Agent, you can write the diff code block directly below the complete code block (separated only by a blank line):

```diff
 func openStore(path string) (*Store, error) {
-	return openWithMode(path, ModeJournal)
+	return openWithMode(path, ModeWAL)
 }
```

Important

A diff fence must immediately follow a complete code block; a standalone diff fence with no preceding code block triggers a diff-orphan error in npx garden check.

3.CJK Bold, Highlighter Strokes, and Callouts

• CJK-friendly bold: remark-cjk-friendly is enabled so **bold next to CJK punctuation** parses cleanly without extra spaces around the asterisks.
• Highlighter stroke: Wrap text in <u>key phrase</u> or <mark>key phrase</mark> to apply a warm yellow highlighter band, like this highlighted phrase.
• Callouts: Supports > [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING], and > [!CAUTION] (plus INFO, SUCCESS, DANGER, and FAILURE). Write a title on the same line after the marker to set a custom heading:

> [!WARNING] Back Up the Data Directory Before Upgrading
> Changing the page size requires rebuilding the index files and cannot be rolled back in place.

Back Up the Data Directory Before Upgrading

Changing the page size requires rebuilding the index files and cannot be rolled back in place.

4.Local Images, Source Chips, and External Link Cards

These three are written in the Markdown body. Rendering rules live on the component pages. This section only records where the files go:

• Local images: For a post at content/posts/my-post.md, put images in content/posts/my-post/ and reference them as ./my-post/diagram.svg. Captions are documented on Local Image.
• Source chips and link cards stay in the prose. See Source Chip and Link Card.

5.Math Formulas and Mermaid Diagrams

• LaTeX math: Rendered at build and server-render time with KaTeX. Use $L = \lambda W$ for inline math and $$...$$ for display blocks. Multi-letter identifiers containing underscores (such as group_num or max_batch) are automatically wrapped as upright \mathrm{group\_num}, while single-letter subscripts like W_q or H_{kv} remain standard math subscripts.
• Mermaid diagrams: Use ```mermaid fences to draw flowcharts or sequence diagrams that adapt to light and dark themes:

graph LR
  A[Markdown Source] --> B[garden sync]
  B --> C[Search & Static Assets]
  C --> D[Rendered Page]

6.Writing Thoughts (content/thoughts/*.md)

Thoughts are short notes with optional image grids, audio/video files, or external link cards:

---
title: Late-Night Debugging Notes
date: 2026-10-19 21:30
tags:
  - Notes
media:
  - type: image
    src: ./rainy-night/terminal.png
    alt: Benchmark output in the terminal
  - type: link
    src: https://sqlite.org/wal.html
    title: SQLite Write-Ahead Logging
---

A short note written in standard Markdown.

The media array accepts four item types: image (multiple images automatically form a grid), audio (native <audio> player), video (native <video> player with optional poster), and link (a card built from the src, title, description, and image you write). Link cards in the body are documented on Link Card.