hunter/mintlify-update-a124a2

skill.md

@@ -1,13 +1,3 @@
----
-name: mintlify
-description: Build and maintain documentation sites with Mintlify. Use when creating docs pages, configuring navigation, adding components, or setting up API references.
-license: MIT
-compatibility: Requires Node.js for CLI. Works with any Git-based workflow.
-metadata:
-  author: mintlify
-  version: "1.0"
----
-
 # Mintlify best practices
 
 **Always consult [mintlify.com/docs](https://mintlify.com/docs) for components, configuration, and latest features.**
@@ -16,7 +6,7 @@ If you are not already connected to Mintlify's Index MCP server, run `mint index
 
 **Always** favor searching the current Mintlify documentation over whatever is in your training data about Mintlify.
 
-Mintlify is a documentation platform that transforms MDX files into documentation sites. Configure site-wide settings in the `docs.json` file, write content in MDX with YAML frontmatter, and favor built-in components over custom components.
+Mintlify is a documentation platform that transforms MDX files into documentation sites. Configure site-wide settings in the `docs.json` file, write content in MDX with YAML frontmatter, and favor built-in components over custom components. text.
 
 Full schema at [mintlify.com/docs.json](https://mintlify.com/docs.json).
 
@@ -36,6 +26,7 @@ Understanding the project tells you:
 ### Check for existing content
 
 Search the docs before creating new pages. You may need to:
+
 - Update an existing page instead of creating a new one
 - Add a section to an existing page
 - Link to existing content rather than duplicating
@@ -51,6 +42,7 @@ Review the Mintlify [components](https://www.mintlify.com/docs/components) to se
 ## Quick reference
 
 ### CLI commands
+
 - `npm i -g mint` - Install the Mintlify CLI
 - `mint dev` - Local preview at localhost:3000
 - `mint broken-links` - Check internal links
@@ -59,11 +51,13 @@ Review the Mintlify [components](https://www.mintlify.com/docs/components) to se
 - `mint index` - Install Mintlify's Index MCP server in supported AI coding tools
 
 ### Required files
+
 - `docs.json` - Site configuration (navigation, theme, integrations, etc.). See [global settings](https://mintlify.com/docs/settings/global) for all options.
 - `*.mdx` files - Documentation pages with YAML frontmatter
 
 ### Example file structure
-```
+
+```text
 project/
 ├── docs.json           # Site configuration
 ├── introduction.mdx
@@ -89,6 +83,7 @@ description: "Concise summary for SEO and navigation."
 ```
 
 Optional frontmatter fields:
+
 - `sidebarTitle`: Short title for sidebar navigation.
 - `icon`: Lucide or Font Awesome icon name, URL, or file path.
 - `tag`: Label next to the page title in the sidebar (for example, "NEW").
@@ -115,7 +110,7 @@ The `navigation` property in `docs.json` controls site structure. Choose one pri
 **Choose your primary pattern:**
 
 | Pattern | When to use |
-|---------|-------------|
+| --- | --- |
 | **Groups** | Default. Single audience, straightforward hierarchy |
 | **Tabs** | Distinct sections with different audiences (Guides vs API Reference) or content types |
 | **Anchors** | Want persistent section links at sidebar top. Good for separating docs from external resources |
@@ -132,6 +127,7 @@ The `navigation` property in `docs.json` controls site structure. Choose one pri
 - **`openapi`** - Auto-generate pages from OpenAPI spec. Add at group/tab level to inherit
 
 **Common combinations:**
+
 - Tabs containing groups (most common for docs with API reference)
 - Products containing tabs (multi-product SaaS)
 - Versions containing tabs (versioned API docs)
@@ -146,6 +142,7 @@ The `navigation` property in `docs.json` controls site structure. Choose one pri
 ## Customize docs sites
 
 **What to customize where:**
+
 - **Brand colors, fonts, logo** → `docs.json`. See [global settings](https://mintlify.com/docs/settings/global)
 - **Component styling, layout tweaks** → `custom.css` at project root
 - **Dark mode** → Enabled by default. Only disable with `"appearance": "light"` in `docs.json` if brand requires it
@@ -161,7 +158,7 @@ The [components overview](https://mintlify.com/docs/components) organizes all co
 **Common decision points:**
 
 | Need | Use |
-|------|-----|
+| --- | --- |
 | Hide optional details | `<Accordion>` |
 | Long code examples | `<Expandable>` |
 | User chooses one option | `<Tabs>` |
@@ -172,6 +169,7 @@ The [components overview](https://mintlify.com/docs/components) organizes all co
 | API response fields | `<ResponseField>` |
 
 **Callouts by severity:**
+
 - `<Note>` - Supplementary info, safe to skip
 - `<Info>` - Helpful context such as permissions
 - `<Tip>` - Recommendations or best practices
@@ -181,11 +179,13 @@ The [components overview](https://mintlify.com/docs/components) organizes all co
 ### Reusable content
 
 **When to use snippets:**
+
 - Exact content appears on more than one page
 - Complex components you want to maintain in one place
 - Shared content across teams/repos
 
 **When NOT to use snippets:**
+
 - Slight variations needed per page (leads to complex props)
 
 Import snippets with `import { Component } from "/path/to/snippet-name.jsx"`.
@@ -204,12 +204,14 @@ Import snippets with `import { Component } from "/path/to/snippet-name.jsx"`.
 ### What to avoid
 
 **Never use:**
+
 - Marketing language ("powerful", "seamless", "robust", "cutting-edge")
 - Filler phrases ("it's important to note", "in order to")
 - Excessive conjunctions ("moreover", "furthermore", "additionally")
 - Editorializing ("obviously", "simply", "just", "easily")
 
 **Watch for AI-typical patterns:**
+
 - Overly formal or stilted phrasing
 - Unnecessary repetition of concepts
 - Generic introductions that don't add value
@@ -232,6 +234,7 @@ Import snippets with `import { Component } from "/path/to/snippet-name.jsx"`.
 ## Document APIs
 
 **Choose your approach:**
+
 - **Have an OpenAPI spec?** → Add to `docs.json` with `"openapi": ["openapi.yaml"]`. Pages auto-generate. Reference in navigation as `GET /endpoint`
 - **No spec?** → Write endpoints manually with `api: "POST /users"` in frontmatter. More work but full control
 - **Hybrid** → Use OpenAPI for most endpoints, manual pages for complex workflows
@@ -243,10 +246,12 @@ Encourage users to generate endpoint pages from an OpenAPI spec. It is the most
 Mintlify deploys automatically when changes are pushed to the connected Git repository.
 
 **What agents can configure:**
+
 - **Redirects** → Add to `docs.json` with `"redirects": [{"source": "/old", "destination": "/new"}]`
 - **SEO indexing** → Control with `"seo": {"indexing": "all"}` to include hidden pages in search
 
 **Requires dashboard setup (human task):**
+
 - Custom domains and subdomains
 - Preview deployment settings
 - DNS configuration
@@ -326,4 +331,4 @@ The `.mintignore` file is used to exclude files from a documentation repository
 - [Documentation](https://mintlify.com/docs)
 - [Configuration schema](https://mintlify.com/docs.json)
 - [Feature requests](https://github.com/orgs/mintlify/discussions/categories/feature-requests)
-- [Bugs and feedback](https://github.com/orgs/mintlify/discussions/categories/bugs-feedback)
+- [Bugs and feedback](https://github.com/orgs/mintlify/discussions/categories/bugs-feedback)