Content — editing rules

Read ../.claude/posts-writing-style.md for the author’s voice and English-editing rules. The points below are layout conventions specific to fenced code blocks in content under this directory.

Code-block captions

Every fenced code block that shows the content of a file must be followed by a <figcaption> whose text is the file’s path or filename. Code blocks that show shell commands or one-shot snippets get a contextual caption (or no caption at all) — never a filename, since there’s no file.

Decision rule:

• The block is what you’d save to disk → caption = the file path you’d save it to.
• The block is something you’d paste into a terminal → caption describes the action, or omit.

Examples:

encoder = vaapi
adapter_name = /dev/dri/renderD128

<figcaption class="code-caption">~/.config/sunshine/sunshine.conf</figcaption> ✓ — file content.

sudo setcap cap_sys_admin+p $(readlink -f $(which apollo))

No caption, or <figcaption class="code-caption">grant KMS capture permission</figcaption> ✓ — shell action.

When you change a file in a post, update the caption to match the file you’re showing. If you move a code block, move its caption with it — don’t leave the caption hanging above an unrelated block.