Skip to main content
This guide is the contributor playbook for creating and updating docs in this project. It covers information architecture, page templates, Mintlify component patterns, validation, and AI discoverability.

​
Docs architecture

docs/
├── docs.json                  # site config + navigation (most important file)
├── index.mdx                  # docs homepage
├── getting-started/           # installation and onboarding
├── concepts/                  # internal architecture and behavior
├── guides/                    # task-based workflows
├── cli/                       # command reference
├── reference/                 # configuration, output, errors reference
└── development/               # contributor and maintenance docs

​
Where new docs go

Content typeFolder
Onboarding, first-rungetting-started/
Design decisions, system behaviorconcepts/
Task recipes, how-toguides/
Flags, options, schemasreference/ or cli/
Contributor processdevelopment/
If a page doesn’t fit one bucket, split the content rather than creating a mixed page.

​
Page frontmatter template

---
title: Your Page Title
sidebarTitle: Short Title
description: One-sentence summary used in search and previews.
icon: book-open
---
Body order:
  1. One concise opening paragraph
  2. Primary workflow (<Steps> when procedural)
  3. Supporting sections (<AccordionGroup>, tables, or examples)
  4. Short checklist or “next steps” links

​
Mintlify components used in this project

NeedComponent
Sequential steps<Steps>
Platform / shell variants<Tabs>
Navigation hubs<CardGroup> + <Card>
Dense details, troubleshooting<AccordionGroup> + <Accordion>
API parameters<ParamField>
High-signal caveats<Note>, <Tip>, <Warning>, <Info>
Code in multiple languages<CodeGroup>
Use code fences with explicit language tags on all blocks (bash, json, python, text).

​
Creating a new page

1

Create the file

Add a new .mdx file in the correct section folder under docs/.
2

Write frontmatter and content

Add title, sidebarTitle, description, and icon. Draft content using existing component patterns.
3

Register in navigation

Add the page path (without .mdx) to the right group in docs/docs.json under navigation.tabs.
4

Add cross-links

Link to at least one related page from the same section and one from an adjacent section.
5

Preview locally

npm i -g mint
cd docs
mint dev
6

Validate

mint broken-links
mint a11y
mint validate

​
Navigation design rules

  • Keep section depth shallow
  • Keep group names task-oriented
  • Prefer one clear home for each page — avoid duplicating a page across multiple groups
  • Keep top-level tabs stable (major user intent only)
  • When reorganizing, update internal links that reference moved pages

​
Content quality checklist

  • Frontmatter is complete and accurate
  • Title and description match the actual content
  • Commands are copy/paste-ready
  • Output examples match current behavior
  • Links are valid and not circular
  • Warnings are used only for real risk
  • No sensitive values (keys/tokens) appear in examples

​
Reusable content

If the same warning, setup snippet, or explanation appears on 2+ pages, make it a reusable snippet and import it. This avoids drift and reduces maintenance.

​
PR checklist for docs changes

  1. Page is in the right section folder.
  2. Page is included in docs/docs.json navigation.
  3. Commands and examples were sanity-checked.
  4. mint broken-links passes.
  5. mint a11y passes.
  6. Cross-links to related docs were added.
  7. Any moved/renamed page has redirects or updated references.

​
Common mistakes

Check that the path in docs/docs.json exactly matches the file path without the .mdx extension.
Concepts, task guides, and reference should each be on their own page. Split rather than blend.
Always run the command and copy real output. Don’t write examples from memory.
Use .mintignore only to fully exclude files from publishing. Use hidden: true in frontmatter to keep a page reachable by URL but out of navigation.