​

HoopAI Docs — Claude Code Instructions

​

Project structure

docs/
├── docs.json              # Site config — theme, nav, colors, branding
├── introduction.mdx       # Landing/intro page
├── quickstart.mdx
├── development.mdx
├── essentials/            # Core guide pages
├── api-reference/         # API docs and endpoint pages
├── images/                # Static assets
├── snippets/              # Reusable MDX components
└── .claude/skills/mintlify/  # Mintlify skill for Claude

​

Workflow

• Preview locally: mintlify dev (runs at localhost:3000)
• Check broken links: mintlify broken-links
• Update CLI: mintlify update

​

Key conventions

• All pages use .mdx extension with YAML frontmatter (title is required)
• Internal links use root-relative paths without extensions: /section/page
• Images go in images/ and always need alt text
• New pages must be added to docs.json navigation or they won’t appear
• Code blocks must have language tags
• Sentence case for headings

​

Verification

​

docs.json

​

Custom styling

• Custom CSS: add a custom.css file and reference it in docs.json under "css": ["/custom.css"]
• Custom JS: add a custom.js file and reference it in docs.json under "js": ["/custom.js"]

​

Mintlify skill

• SKILL.md — components, config, navigation, CLI reference
• reference/components.md — all 24 components with full props
• reference/configuration.md — complete docs.json schema
• reference/navigation.md — nav patterns (tabs, anchors, dropdowns)
• reference/api-docs.md — OpenAPI/AsyncAPI setup, Hoop AI API import
• reference/authoring.md — writing principles, page templates, style guide
• reference/workflows.md — new-doc, URL-to-doc, Playwright verification