> ## Documentation Index > Fetch the complete documentation index at: https://docs.gridshift.studio/llms.txt > Use this file to discover all available pages before exploring further. # STYLE # Documentation style spec **v0.1** · The single, operational spec for how Gridshift docs are written and structured. It governs everything under `docs/` (Mintlify). Voice and brand rules live in [`BRAND.md`](../BRAND.md) (repo root) — this file is the docs-specific operationalization of them, and the checklist the `/docs-audit` skill enforces. If a rule here and `BRAND.md` ever disagree, `BRAND.md` wins on voice; this file wins on structure and Mintlify usage. *** ## 1. Voice, in one paragraph Docs are the literal end of [register by altitude](../BRAND.md) — no marketing, ever. Write to a producer who is technical and impatient with fluff. Present tense, imperative for actions ("Press `⌘U`", not "You can press ⌘U"). **US English** (color, behavior, optimize, canceling, gray). Bold a domain term **once**, on first use, then plain. Cut the first sentence if it's throat-clearing. No exclamation marks, no emoji. *** ## 2. Page anatomy Every feature page follows the same spine: 1. **Frontmatter** (see §3). 2. **One-sentence definition** — opens the page, bolds the key term once. > **Quantize** snaps the start of notes and audio transients to the nearest grid position. 3. **How it works** — the mental model, briefly. Why it behaves as it does. 4. **Task sections** — one per thing the user does, task-oriented sentence-case headings (*"Quantize a selection,"* not *"Quantization"*). Steps inside. 5. **Shortcuts** — a table, when the feature has them. 6. **Related / caveats** — cross-links and edge cases, via callouts. Concept pages (`concepts.mdx`, `introduction.mdx`) explain the model and may skip the task sections. Shortcut-reference pages are primarily tables. **Headings:** sentence case, task-oriented, verb-first where it's an action. Never Title Case a heading (feature *names* inside prose stay Title Case — they're proper nouns; see §6). *** ## 3. Frontmatter | Key | Required | Rule | | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `title` | **yes** | The feature's canonical name (§6). Title Case for the proper noun. | | `description` | **yes** | One sentence, sentence case, no trailing period-stuffing. This is the search-result line and the SEO description — make it say what the feature *does*. | | `sidebarTitle` | recommended | Short form for the nav when `title` is long. | | `icon` | recommended | A Lucide icon name, consistent with sibling pages in the group. | | `reviewed` | managed | ISO date the page was last **verified against the code** (§6). Written by `/docs-audit`; don't backfill by hand. Missing = never verified. | | `verifiedAgainst` | optional | App/build version the page was checked against, alongside `reviewed`. | ```mdx theme={null} --- title: "Quantize" sidebarTitle: "Quantize" description: "Snap notes and audio transients to the grid, by a chosen amount." icon: "grid" reviewed: 2026-07-11 --- ``` `reviewed` is the freshness signal — it means *last checked for accuracy*, which is what predicts staleness. It is **not** an edit date: git already records edits, and Mintlify shows a git-based "last updated" (`metadata.timestamp`). Never hand-set `reviewed` — a date no audit produced is a claim no one checked. *** ## 4. Components — when to use which Use the smallest thing that does the job. A sentence beats a callout; a callout beats a section. Never stack callouts, never decorate. | Element | Use it for | Don't | | ------------------------ | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | `` / `` | Any procedure of 2+ ordered actions. Prefer over a bare numbered list — it renders the sequence clearly. | Single actions (just write the sentence). | | `` | A caveat or aside that qualifies the main text. | General prose that belongs in the body. | | `` | A power-move, shortcut, or workflow accelerator. | Restating a step. | | `` | A prerequisite or piece of background context. | Warnings — use ``. | | `` | **Reserved** for data loss or irreversible actions only. | Ordinary caveats (that's ``). | | `` | Wrapping a screenshot or image, with a caption. | Text. Every product image lives in a ``. | | `` / `` | Navigation / overview grids (e.g. a feature index). | Inline emphasis inside a page body. | | Tables | Setting × behavior, mode × behavior, shortcut × action. | Prose that isn't really tabular. | | `` `inline code` `` | Shortcuts (with glyphs), parameter names, values, file/menu paths. | Emphasis (use bold). | `` and `` are sanctioned but not yet used across the docs — introduce them where they fit; don't retrofit mechanically. *** ## 5. Conventions * **Shortcuts:** real glyphs in inline code, no `+`: `` `⌘U` ``, `` `⌥A` ``, `` `⌘⇧D` ``. Modifier order: ⌃ ⌥ ⇧ ⌘. * **Command Palette paths:** `Command Palette → **Set Record Quantize**` — bold the command name. * **Feature names:** exact canonical casing from the [BRAND.md glossary](../BRAND.md). Never lowercase or hyphenate a variant. Platform names keep their casing: MIDI, iOS, iCloud, macOS, MCP. * **Cross-links:** relative, by canonical name — `[Groove & Swing](/features/groove)`. * **Numbers & units:** numerals for measured values, space before the unit — `48 kHz`, `256 frames`, `5 ms`. * **Defaults:** always state the current default, and mark it — `**None** (default)`. *** ## 6. Accuracy contract This is what makes a doc *correct*, not just well-formed. Every one of these is a **checkable claim** and must match the current code: * Keyboard shortcuts and modifier combos. * Default values and the set of available options / modes / enum cases. * Parameter, control, and setting names (as shown in the UI). * Command Palette command names and menu paths. * File locations, formats, and limits stated as fact. * Stated behavior that the code actually implements. When a claim can't be verified from code (subjective/behavioral prose), it is **flagged for human review**, not silently rewritten. *** ## 7. Definition of done A page passes audit when all of these hold: * [ ] Frontmatter has `title` + `description`; `description` is one sentence, sentence case, US English. * [ ] Opens with a one-sentence definition; key term bolded once. * [ ] Headings are sentence case and task-oriented. * [ ] Procedures use ``; callouts follow §4; no stacked/decorative callouts. * [ ] Shortcuts use glyphs in inline code; feature names match the glossary; US English throughout. * [ ] Every checkable claim (§6) matches current code, or is flagged for review. * [ ] Length fits the content — a feature page is typically \~40–100 lines. No padding. * [ ] Cross-links resolve and use canonical names.