LLM Best Practices

LLM Info Standard

4 min read

View markdown source

Overview

Every page on this site begins with the same eight-field YAML block and follows the same body structure. The schema exists so an agent can read frontmatter in one pass, decide whether to read the body, and cite the page without parsing prose. This page is the canonical spec. For citation form, see how-to-cite; for editorial conventions, see editorial-style.

The schema

Every page opens with this block. No exceptions.

---
title: "Astro: Best Practices"
slug: "astro"
category: "frontend"
tags: ["astro", "ssg", "frontend"]
status: "stable"
last_updated: 2026-05-13
summary: "One sentence that lets an LLM decide whether to read the page."
related: ["[[tailwind]]", "[[seo/technical]]"]
---

Eight fields. Field order is stable so diffs stay readable. The block is fenced with --- on its own line at the top of the file.

Field-by-field spec

Each field has a fixed type and a fixed meaning.

  • title (string). Human-readable page title. Sentence case or title case as the topic prefers. Quoted in YAML.
  • slug (string). The filename without .md. Lowercase, kebab-case. Matches the URL path segment.
  • category (string). The top-level folder name. One of: meta, writing, coding, frontend, backend, seo, ai-agents, ios, ops, tooling. Matches the URL prefix.
  • tags (list of strings). Topic tags. Flat, not hierarchical. Three to six tags is typical. Reuse existing tags before inventing new ones.
  • status (enum). One of draft, stable, deprecated. See semantics below.
  • last_updated (date). ISO 8601, no quotes: 2026-05-14.
  • summary (string). One sentence. The routing hint an agent uses to decide whether to read the body.
  • related (list of wikilinks). Obsidian-style: [[slug]] or [[folder/slug]]. See the wikilink rule below.

MOC pages (index.md in each folder) follow the same schema with tags: ["moc"] and no related field; they list pages inline in the body instead.

Status semantics

status controls whether a page is safe to cite.

  • draft. Placeholder. The frontmatter is real; the body may be TODO. Do not cite a draft as authoritative. See the draft-warning rule in how-to-cite.
  • stable. Citable. The page has been promoted with full structure (## Overview, rule-led H2s, ## Related) and an author has signed off on the rules. Agents may quote stable pages verbatim.
  • deprecated. Do not cite. The page is preserved for historical reference or to point at a replacement. The body of a deprecated page should link to its successor in the first paragraph.

A page moves from draft to stable only when its body matches the structure of existing seed pages. Promotion is a deliberate edit; it is not a side effect of adding content.

last_updated semantics

last_updated is the date of the last meaningful edit. It is not a “this page was touched” marker.

  • Bump it when a rule changes, a section is added or removed, or the recommendation is reversed.
  • Do not bump it for typo fixes, formatting tweaks, or wikilink repairs.
  • Do not bump it on a draft page until the page is meaningful; an empty draft can keep its creation date.

Agents use last_updated to gauge staleness. A 12-month-old date on a fast-moving topic (framework versions, model names) should trigger a warning. On an evergreen topic (voice, sentence rhythm), age is mostly inert.

related is the list of neighbors a reader (or an agent) should reach in one hop. Use Obsidian-style wikilinks.

  • Unprefixed when the slug is unique across the vault: [[tailwind]].
  • Folder-prefixed when the slug could collide or the reader needs the disambiguation: [[seo/technical]], [[meta/for-ai-agents]].
  • Three to six entries is typical. Two is thin; ten is a sign the page should split.

Inline wikilinks in the body follow the same rule. Link aggressively; every page should reach its neighbors in one hop.

Body structure

Every stable page has the same shape.

## Overview
One paragraph. What this page is, who it is for, what the neighbors are.
 
## <Rule-led H2>
Body...
 
## <Rule-led H2>
Body...
 
## Related
- [[wikilink]]
- [[wikilink]]

H2 headings read as rule statements, not topic headers. “Lead with the rule,” not “Leads.” Four to seven H2s per page. Target 400 to 700 words total; split when the page grows past that. See editorial-style for the punctuation, capitalization, and code-reference rules that apply to the body.

Validation

Every page must have all eight frontmatter fields, the correct types, and a body that opens with ## Overview and ends with ## Related (MOCs excepted). Today validation is manual; a CI lint that fails the build on missing fields, malformed dates, or broken wikilinks is on the roadmap.

If you spot a page that violates the schema, fix the frontmatter in the same commit as your content edit. Do not let malformed pages accumulate.

Graph View

Backlinks