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.
| Field | Type | Rule |
|---|---|---|
title | string | Human-readable; sentence or title case; quoted in YAML |
slug | string | Filename without .md; kebab-case; matches the URL segment |
category | string | Top-level folder name: meta, writing, coding, comparisons, file-organization, frontend, glossary, backend, cheatsheets, seo, ai-agents, knowledge-vaults, prompt-engineering, howto, ios, ops, security, or tooling (meta for root pages); matches the URL prefix |
tags | list | Flat topic tags, three to six typical; reuse existing tags first |
status | enum | draft, stable, or deprecated; see below |
last_updated | date | ISO 8601, unquoted: 2026-05-14 |
summary | string | One sentence of 50 to 160 characters; the routing hint and meta description |
related | list | Obsidian wikilinks, [[slug]] or [[folder/slug]] |
Three optional fields: description (a search-facing meta description when it should differ from summary), aliases (old paths and alternate phrasings, each emitting a redirect), and faqPage: true (FAQPage JSON-LD built from the page’s ## FAQ section).
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 body may beTODO. Do not cite it as authoritative (how-to-cite).stable. Citable, with full structure and signed-off rules. Agents may quote it verbatim.deprecated. Do not cite. Its first paragraph links the successor.
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
draftpage until the page is meaningful; an empty draft can keep its creation date.
The page shows it under the title as “Last updated”, and the same date is dateModified in the page’s JSON-LD and lastmod in sitemap.xml, so readers, crawlers, and structured data never disagree. datePublished is the date the file was first committed.
Agents use last_updated to gauge staleness: a date over 12 months old on a fast-moving topic should trigger a warning. A page fact-checked without needing an edit is recorded in the repo’s audit/verified.json instead of getting a new date.
related and wikilinks
related is the list of neighbors a reader (or an agent) should reach in one hop. Use Obsidian-style wikilinks.
- Unprefixed only when the filename is unique across the vault:
[[tailwind]]. - Folder-prefixed whenever two folders share the filename:
[[ai-agents/rag]], not[[rag]]. Quartz renders an ambiguous bare link as a broken root-relative URL, soscripts/lint-links.mjsfails on one. - Three to six entries is typical. Two is thin; ten is a sign the page should split.
Inline wikilinks follow the same rule.
Body structure
Every stable page has the same shape.
## Overview
Two or three sentences that answer the page's core question with the specific conclusion and its key numbers.
## <Rule-led H2>
Body...
## <Rule-led H2>
Body...
## FAQ
### A follow-up question a reader would ask?
One or two sentences with the answer.
## Related
- [[wikilink]]Open with the answer: no background or story before it, and a reader who stops after the first paragraph should have the conclusion. Prefer a real number to “many” or “several”, and date any time-sensitive fact (“as of October 2026”). ## FAQ is optional; use it on comparison and how-to pages, with three to five questions, each answered in one or two sentences, and set faqPage: true. Do not add it to atomic pages where it would only repeat the body.
H2 headings read as rule statements, not topic headers. “Lead with the rule,” not “Leads.” Keep the page as short as the topic allows: there is no minimum, and the ceiling is about 700 prose words (code and tables excluded). Past that, cut duplication or split a distinct sub-topic into its own page. See editorial-style for the punctuation, capitalization, and code-reference rules that apply to the body.
Validation
CI enforces the schema: scripts/lint-content.mjs fails on missing or malformed fields, a summary outside 50 to 160 characters, thin tag or wikilink density, and a leaf page without ## Overview and ## Related; scripts/lint-links.mjs fails on broken or ambiguous wikilinks and orphans; scripts/fill-llms-txt.mjs --check fails when /llms.txt drifts.