Documentation Guide

This guide covers how to create and maintain documentation in the astro-agency docs system. Every feature implementation must include a corresponding documentation page.

Who this is for

• Implementors creating docs for features they deliver
• AI agents generating docs as part of implementation work packages
• Developers maintaining system-level documentation

Adding a Documentation Page

1. Create a markdown file in src/core/content/theme-docs/ (CORE-OWNED — theme documentation is maintained in the core, not in site-level content):

src/core/content/theme-docs/my-feature.md

2. Add the required frontmatter (see schema below).
3. Write the content using ## and ### headings to populate the table of contents.
4. Run the build to verify the page renders and frontmatter validates.

Frontmatter Schema

The docs collection schema is produced by the defineDocsCollection() factory in src/core/config/docs-collection-factory.ts and enforced by Zod at build time. Theme-docs calls the factory in src/core/config/theme-docs-collection.ts with governance-specific extensions. For an overview of all content collections (not just docs), see the Content Collections reference (DOC-00005). For the full Docs Kit system, see the Docs Kit guide (DOC-00080).

Required Fields

Field	Type	Notes
title	string	Page title. Appears as the <h1> and in listings.
description	string	Short summary (1–2 sentences). Used in listing cards and <meta name="description">.
docId	string	Format: DOC-NNNNN (e.g. DOC-00001). Must be unique across all docs. Assign the next unused number.
topic	string	Groups related docs. Must be a key from the topic registry.
audience	string[]	Minimum 1 item. Values: implementor, developer, editor.
docType	string	Categorises the doc. Base values: guide, reference, policy, how-to, tutorial, overview, topic-index. Collections may register additional types — see Collection-Specific Doc Types.

Optional Fields

Field	Type	Default	Notes
order	integer	—	Sort position in listings. Lower numbers appear first. Convention: 1 for topic-indexes, 2 for entry points, 11+ for regular docs (alphabetical, +1 increments), 800+ for showcases and layout-recipes.
datePublished	date	—	Publication date. Use ISO format (2026-02-26).
dateModified	date	—	Last modified date.
draft	boolean	false	Draft docs are excluded from listings, sitemap, and search.
deprecated	boolean	false	Deprecated docs remain routable but are excluded from listings and search. A deprecation banner appears on the page.
supersededBy	string	—	DOC-NNNNN of the replacement doc. Only valid when deprecated: true. The deprecation banner links to this doc.
heroTitle	string	—	Alternative display title. Overrides title for the rendered <h1> while title remains the SEO/tab title.
shortTitle	string	—	Abbreviated title for navigation labels, breadcrumbs, and card titles.
toc	boolean	true	Set to false to suppress the table of contents on the page.
showRequirements	boolean	true	Set to false to suppress the related requirements section.
relatedDocs	string[]	—	Array of DOC-NNNNN IDs to cross-link. Renders a related docs section at the bottom of the page.
canonical	string	—	URL override. Must be an absolute URL or a site-relative path starting with /.
tocStartLevel	integer	2	Lowest heading level included in the table of contents (1–6).
tocEndLevel	integer	3	Highest heading level included in the table of contents (1–6).
linkedRoute	string	—	Theme-docs only. Route path for showcase and layout-recipe metadata stubs (e.g. /theme-docs/showcase/showcase-tokens/).

Example Frontmatter

---
title: Navigation System
description: How the primary, utility, and mobile navigation systems work and how to configure them.
docId: DOC-00019
topic: configuration
audience:
  - implementor
  - developer
docType: reference
order: 19
datePublished: 2026-02-26
draft: false
relatedDocs:
  - DOC-00018
---

Content Standards

Structure

Every doc should follow this general structure:

1. Opening paragraph — 1–3 sentences stating what the page covers and why it matters. No need to repeat the title as a heading; the frontmatter title renders as the <h1>.
2. “Who this is for” — a short bulleted list identifying the intended audience and their use case. Helps readers quickly decide if the page is relevant to them.
3. Body sections — the main content, organized under ## headings. Each section should cover one concept or task.
4. Cross-references — link to related docs using relative paths or DOC-NNNNN references where the docs system supports it.

Writing Style

• Be direct. Lead with the most useful information. Don’t bury instructions under background context.
• Be specific. Use file paths, config keys, and code examples rather than abstract descriptions. Readers should be able to act on the content without guessing.
• Be concise. One clear sentence beats two vague ones. Cut filler phrases (“it should be noted that”, “in order to”).
• Use examples. Show a frontmatter block, a config snippet, or a file path for every concept you introduce. Examples are the fastest way to communicate structure.
• Use tables for structured data. Config fields, schema properties, and option lists are easier to scan in table format than in prose.
• Use code blocks for paths and commands. Inline code for field names and short values; fenced blocks for multi-line examples.

Level of Detail

Match detail to the doc type:

Doc Type	Detail Level	Focus
guide	Step-by-step with examples	Walk the reader through a complete task from start to finish.
reference	Comprehensive field/API coverage	Document every field, option, and behavior. Readers use this as a lookup, not a tutorial.
how-to	Focused on a single task	Assume the reader knows the system; show the shortest path to accomplish the goal.
policy	Rules and rationale	State what must be done, why, and what happens if it isn’t.
overview	Conceptual with navigation	Introduce a topic area: what it is, who it’s for, key concepts, and reading order for related docs. No implementation detail — link to reference and how-to docs instead.
topic-index	Conceptual with navigation	Entry point for a topic directory. Same structure as overview but specifically used for index.md files that serve as the landing page for a topic. See Overview Intro Pages.

Evergreen principle: Docs should teach the system — naming rules, models, mechanisms, file locations — not exhaustively list every value. Use representative samples (2–3 examples per category) to illustrate conventions, and point readers to the authoritative source files for complete inventories. This prevents docs from going stale when values change and avoids requiring doc updates for every small code change.

Collection-Specific Doc Types

The defineDocsCollection() factory accepts an additionalDocTypes parameter that extends the base enum. Theme-docs registers two additional types in src/core/config/theme-docs-collection.ts:

Doc Type	Purpose
showcase	Visual QA page rendered from code, not markdown. The file is a metadata stub — frontmatter only, no body content. Uses linkedRoute to point to the Astro route that renders the showcase.
layout-recipe	Layout demonstration page, also a metadata stub. Same pattern as showcase: frontmatter-only with linkedRoute.

Showcase and layout-recipe files are exempt from content structure requirements (opening paragraph, “Who this is for”, body sections). Their purpose is to register the page in the docs collection for indexing and navigation while the actual rendering is handled by Astro components at the linked route.

Overview Intro Pages

Every topic has an intro page (index.md in its topic directory) with docType: topic-index. These pages serve as entry points for each topic area. Each intro follows this structure:

1. Opening paragraph — what this topic area covers (2-3 sentences)
2. Who this is for — bulleted list by audience role and what they’ll get from this topic
3. Key concepts — the mental model, brief and conceptual, no implementation specifics
4. Reading order — ordered list of related docs with one-line descriptions
5. Related topics — cross-topic links via relatedDocs frontmatter

Intro pages should remain useful even if every doc they link to gets rewritten. They teach the model, not the specifics.

Headings

• Never author a prose # heading in docs content. The page <h1> is rendered from frontmatter title (or heroTitle when set).
• Start body content at ## level.
• Use ### for subsections. Avoid going deeper than #### — if you need more nesting, consider splitting into separate docs.
• Headings should be scannable on their own. “Configuration” is too vague; “Site Identity Configuration” tells the reader what they’ll find.
• # is still valid inside fenced code blocks when demonstrating shell comments or markdown syntax.

Charter Traceability

Every documentation page that describes a feature, configuration surface, or system behavior must cite the charter section(s) it implements using (§N) notation. This keeps docs traceable to the source decisions in .docs/charter.md.

Where to add references:

• Section headings — append the charter section: ## Contact & Legal
• Table captions or introductory lines — cite inline: Nested under contact: ContactConfig.
• Type/interface descriptions — cite in the opening sentence: The menu configuration contract defines navigation structures.

In code (JSDoc):

/** Contact & Legal */
contact: ContactConfig;

/** Main navigation */
mainNav: MainNavConfig;

Accessibility in Content

• Every image must have meaningful alt text (not “screenshot” or “image”).
• Use semantic heading hierarchy — don’t skip levels.
• Tables must have header rows.
• Code blocks should specify the language for syntax highlighting.
• Do not use markdown task-list syntax (- [ ], - [x]). It renders as <input type="checkbox"> elements outside a <form>, which is invalid HTML. Use plain bullet points instead.

Assigning a docId

Each doc gets a unique DOC-NNNNN identifier. To assign one:

1. Check the highest existing docId across all docs in src/core/content/theme-docs/.
2. Increment by 1.
3. Duplicate docId values cause a build error.

The docId is immutable once assigned. If a doc is deprecated, its docId is not reused.

Deprecating a Doc

When a doc is outdated and replaced by a newer one:

1. Set deprecated: true in the frontmatter.
2. Set supersededBy: DOC-NNNNN to point to the replacement doc (optional but recommended).
3. Update the requirements catalog: search src/core/config/requirements.catalog.ts for the deprecated docId in appliesTo arrays and replace it with the successor’s docId. Requirements link to docs via appliesTo — stale references cause requirements to render on the deprecated page instead of the replacement.
4. Update relatedDocs references: search all theme-docs frontmatter for the deprecated docId in relatedDocs arrays and replace it with the successor’s docId.
5. Update inline links: search the entire repo for URL-path links to the deprecated doc (e.g., /theme-docs/platform/best-practices/) and markdown file links (e.g., ./best-practices.md) and point them to the successor’s route or file instead.
6. The doc remains accessible at its existing URL — no links break.
7. The doc is excluded from the docs index listing and search results.
8. A deprecation banner appears at the top of the page with a link to the successor.
9. Related docs lists show deprecated docs with a “(deprecated)” indicator.
10. Deprecated docs are excluded from prev/next navigation.

The docId of a deprecated doc is never reused.

Do not delete deprecated docs. They preserve history and prevent broken links from external sources.

Available Topics

Topics group docs for navigation and filtering. Each docs collection defines its own canonical topic list as a readonly tuple passed to the defineDocsCollection() factory. The schema enforces valid values at build time — any unrecognized topic causes a build error.

Theme-docs: The canonical topic list is the THEME_DOC_TOPICS array in src/core/config/theme-docs-collection.ts (CORE-OWNED). Topic ordering and display labels are in src/core/config/theme-docs-defaults.ts.

Site-docs: The canonical topic list is the SITE_DOC_TOPICS array in src/site/config/site-docs.ts (SITE-OWNED). Topic ordering and display labels are in the same file.

To add a new topic, add it to the relevant collection’s topic tuple and update the corresponding topic config array with a label and sort order.

When to Create a Doc

• Every feature implementation must include a doc covering what was built, how it works, and how to configure or extend it.
• System-level changes (architecture, token contracts, validation gates) require a reference doc or an update to an existing one.
• Configuration surfaces (site.ts fields, nav config, token overrides) require a reference doc listing every field, its type, default, and purpose.

Docs are created during implementation, not postponed.