Documentation contract
Language and voice
Section titled “Language and voice”Write in clear, simple, user-focused language. Use active voice and present tense. Use sentence case for headings.
Page structure
Section titled “Page structure”Do not repeat the frontmatter title as another H1. Start page content with H2 sections. Every page requires title and description frontmatter.
Links and media
Section titled “Links and media”Use relative links inside the same product. Absolute Hub routes must be one of /, /products/, /documentation-contract/, /architecture/, /contributing/, or /products/<this-spoke-id>/.... Link schemes other than http, https, mailto, and tel are rejected (javascript:, data:, vbscript:, file:). Add meaningful alt text to images. Keep assets under docs/assets/. Files under docs/assets/ must stay at or under 20 MiB. Hub ingest sanitizes .svg files (scripts, event handlers, and unsafe URLs are stripped from the generated copy).
Procedures
Section titled “Procedures”Explain prerequisites before procedures. Keep commands and code examples complete and runnable. Mention expected results after important commands.
What not to use
Section titled “What not to use”Do not use raw HTML, unsupported components, or Mintlify-specific MDX. Spoke documentation uses Markdown (.md) only during the MVP. Update examples when related APIs or commands change.
Spoke layout
Section titled “Spoke layout”Every Spoke must contain docs/index.md. Pages are Markdown (.md) only.
getting-started/, guides/, reference/, and assets/ are the recommended information architecture. Create a directory when you have pages or media for it — empty folders are not required. Put images and other media under docs/assets/ when you add them.
Page and directory names use lowercase kebab-case. Each Spoke receives a unique /products/<spoke-id>/ route.