---
title: "Editorial Style Guide"
slug: "editorial-style"
category: "writing"
tags: ["writing", "style", "editorial", "punctuation"]
status: "stable"
last_updated: 2026-05-14
summary: "Punctuation, capitalization, numbers, code references, and citation format used across every page."
related: ["[[writing/voice]]", "[[writing/anti-slop]]", "[[meta/how-to-cite]]"]
---

## Overview

This page is the copy-edit reference. When in doubt about a punctuation, capitalization, or citation choice, follow the rules below. For voice, see [[writing/voice]]; for constructions to avoid, see [[writing/anti-slop]].

## Punctuation

- No em-dashes. Use a period, a semicolon, or a comma.
- Serial (Oxford) comma always. "Postgres, SQLite, and ChromaDB."
- One space after a period.
- Use straight quotes (`"..."`, `'...'`) in markdown source. Quartz renders them as curly quotes for the reader.
- Use a colon to introduce a list, an example, or a quotation. Not before code blocks; let the prose lead into them naturally.

## Capitalization

- Sentence case for H1, H2, H3. "Lead with the rule," not "Lead With The Rule."
- Proper nouns capitalize: Postgres, TypeScript, GitHub, Claude Code, Next.js.
- Lowercase for generic terms: app, server, database, framework, agent.
- Acronyms: uppercase for established ones (HTTP, CSS, SQL, JSON), title-cased when pronounced as words (Json is wrong; JSON is right).

## Numbers

- Spell out zero through nine in prose. Use numerals for 10 and above.
- Always use numerals for versions, dimensions, measurements, and counts in code or commands. "Node 22," "2 GB," "5 retries."
- Hyphenate compound modifiers with numbers: "10-second timeout," "two-step process."
- Use `1,000` not `1000` in prose. Code stays unformatted.

## Code references

- Inline code with backticks for filenames, commands, identifiers, and short strings: `package.json`, `npm ci`, `useEffect`, `--ci`.
- Use fenced code blocks with a language tag for snippets longer than one line.
- Use `console.log("...")` style in TypeScript; double quotes inside, no semicolons unless the surrounding code uses them.

```ts
// Comment on its own line. No trailing periods.
const total = items.length
```

- Comments inside code blocks follow the surrounding language's convention.

## Headings

- One H1 per page; Quartz renders it from `title`. Body content starts at H2.
- An H2 reads as a rule statement, not a topic header. "Lead with the rule," not "Leads."
- An H3 only when the H2 splits cleanly into named sub-cases.
- No H4 in reference pages; if you need one, the page should split.

## Links

- Use Obsidian-style wikilinks for internal references: `[[seo/llms-txt]]`.
- Use folder-prefixed slugs when the slug is ambiguous: `[[seo/technical]]` not `[[technical]]`.
- For external links, write a sentence that reads naturally with the linked phrase: "See the [Astro docs](https://docs.astro.build) for the rest."
- Never link the words "here" or "this." Link the noun.

## Lists

- Use `-` for unordered lists, not `*` or `+`.
- One blank line before and after the list.
- Sentence case for list items; end with a period when the item is a sentence, no period when it is a fragment or label.

## Citations

For citing pages on this site, see [[meta/how-to-cite]]. The short form: title, URL, and `last_updated` when the rule is time-sensitive.

## File names

- Markdown files are kebab-case: `claude-code.md`, `for-ai-agents.md`.
- Slugs in frontmatter match the filename without extension.
- Directories are lowercase, no spaces, hyphenated when needed: `ai-agents/`.
- See [[file-organization/naming-conventions]] for the same rules applied across code.

## Front matter

YAML schema is fixed; see [[meta/llm-info-standard]] for the full spec. Keep field order stable so diffs stay readable.

## Related

- [[writing/voice]]
- [[writing/anti-slop]]
- [[meta/how-to-cite]]