LLM Best Practices

Editorial Style Guide

3 min read

View markdown source

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 voice; for constructions to avoid, see 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.
// 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.
  • 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 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 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/.

Front matter

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

Graph View

Backlinks