For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /packs/shared/documentation/formatting.md.
Quick start

Formatting

Format each page so it still works when read as a local file or copied with the complete pack.

Why

The same reference material is read by Almanac, the docs site, and a filesystem agent. Brief metadata and portable links let those readers use one source page.

Rules

  • MUST give standard pages matching frontmatter/H1 titles and a quoted description no longer than 120 characters. [review]
  • MAY leave README indexes without frontmatter. [review]
  • MUST link to sibling pack material with relative file paths while no site routes exist for it. [review]
  • MUST spell external references as complete URLs. [review]
  • MUST restrict metadata to facts about the page until an approved manifest contract defines other fields. [review]
  • MUST keep local-machine absolute paths and source-checkout-dependent links out of portable guidance. [review]

[review]

Granary's component-content tests check standard metadata and heading structure; oxfmt checks formatting. Installed-link tests establish local-link closure. Review checks portable meaning and executable examples.

Content

Why

A reader should know whether a fence contains a command, configuration, or source code. Concrete examples also reveal prerequisites that a shortened sketch can hide.

Rules

  • MUST label every fenced block with its language. [review]
  • MUST use specific values and include only the lines needed to demonstrate the rule. [review]
  • MUST present executable commands in fences and field or option mappings in tables. [review]
  • MUST finish normative bullets with a period. [review]
  • SHOULD keep punctuation consistent across the remaining list items. [review]
  • MUST provide complete runnable examples instead of placeholder omissions when direct execution is intended. [review]
  • MUST delegate document formatting to oxfmt. [review]

See Diagrams for visual models and directory trees.

[review]

Granary's component-content tests check standard metadata and heading structure; oxfmt checks formatting. Installed-link tests establish local-link closure. Review checks portable meaning and executable examples.

Enforcement

Granary's component-content tests check standard metadata and heading structure; oxfmt checks formatting. Installed-link tests establish local-link closure. Review checks portable meaning and executable examples.