Authoring conventions — BASE docs
Working note for everyone (humans + agents) writing pages in this repo. Keep it short; the QA gates inscripts/ enforce the hard rules automatically.
Component whitelist
Use ONLY these Mintlify components. Anything else is rejected in review:CardCardGroupStepsTipTabsAccordion
Note, Warning, Frame, custom MDX
components, etc.) without an explicit decision recorded here first.
Cite-or-omit rule
Every factual/technical claim MUST be traceable to a pinned source inSOURCES.md. If you cannot cite a canonical source for a statement, omit it —
do not guess, infer, or paraphrase from memory.
- Canonical source of truth: BASE/
base(pinned SHA inSOURCES.md). - Never source content from
PlatformNetwork/*or any non-BASE org. - If a value is known but not yet confirmed against source, mark it with the
approved
unverifiedtoken (the only placeholder the gates allow) and open an item inissues.md.TODO/FIXME/loremare forbidden.
Frontmatter template
Every.mdx page starts with YAML frontmatter:
titleanddescriptionare required on every page.- Use sentence case for
title. - Optional keys when relevant:
icon,sidebarTitle.
Terminology (preferred usage)
Use these terms exactly; do not invent synonyms.
Network-specific facts (e.g.
netuid 100) must match SOURCES.md.
Brand colors
- Primary red:
#d91f35 - Success green:
#b2ff22(ALLOWED — whitelisted by the forbidden-string gate) - Forbidden starter greens:
#16a34a,#07c983,#15803d(gate fails on these) - Forbidden paid font:
argent-pixel/pjc8nxd
Style
- Active voice, second person (“you”).
- One idea per sentence; keep them concise.
- Sentence case for headings.
- Bold for UI elements (e.g. Click Settings).
- Code formatting for file names, commands, paths, and code references.
Local QA gates
Run before every commit / PR (seescripts/):
PASS/FAIL summary.