Contributing to Docs

​

Where the docs live

​

How to add a new page

1. Create an .mdx file under docs/mintlify/ in the appropriate folder (guides/, reference/, hardware/, channels/, etc.). Use the standard frontmatter:
   ---
   title: "My New Page"
   description: "One-sentence summary for search + SEO."
   ---
   
2. Add the page to the navigation in docs/mintlify/docs.json under the right group. Example:
   {
     "group": "Guides",
     "pages": [
       "guides/existing-page",
       "guides/my-new-page"
     ]
   }
   
3. Commit and push to main. Mintlify auto-deploys in ~1 minute.

​

Editing existing pages

​

Previewing locally

npm i -g mintlify
cd docs/mintlify
mintlify dev

​

Style conventions

• Use frontmatter title + description on every page (powers search + OG)
• Use Mintlify components for callouts: <Note>, <Warning>, <Tip>, <Check>
• Code fences with language: py, bash, jsx, swift, kotlin
• Link between docs pages with relative paths: [See Skills](/guides/skills)
• External repo links use full URLs

​

How deployment works

• main branch = production docs
• Mintlify validates docs.json and every page on build
• A broken page reference in docs.json fails the whole deploy — check Mintlify dashboard for errors

​

Troubleshooting

• 404 after push: page not in docs.json navigation
• Mintlify build fails: docs.json references a non-existent page, OR frontmatter is malformed
• Broken link: relative paths are case-sensitive; use all-lowercase filenames and matching references
• Search not finding a page: missing or empty description in frontmatter