--- title: "LLM Info Standard" slug: "llm-info-standard" category: "meta" tags: ["meta", "schema", "yaml"] status: "stable" last_updated: 2026-05-14 summary: "The YAML frontmatter schema and body conventions every page on this site follows." related: ["[[meta/for-ai-agents]]", "[[meta/how-to-cite]]", "[[writing/editorial-style]]"] --- ## 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 [[meta/how-to-cite]]; for editorial conventions, see [[writing/editorial-style]]. ## The schema Every page opens with this block. No exceptions. ```yaml --- 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`, `comparisons`, `file-organization`, `frontend`, `glossary`, `backend`, `cheatsheets`, `seo`, `ai-agents`, `prompt-engineering`, `howto`, `ios`, `ops`, `security`, `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 [[meta/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` and wikilinks `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. ```markdown ## Overview One paragraph. What this page is, who it is for, what the neighbors are. ## Body... ## 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 [[writing/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). Validation runs in CI: `scripts/lint-content.mjs` fails the build on missing fields, malformed dates, invalid status, or thin tag/wikilink density, and `scripts/lint-links.mjs` fails on broken wikilinks. 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. ## Related - [[meta/for-ai-agents]] - [[meta/how-to-cite]] - [[writing/editorial-style]]