From 171d587ff93f4f27153d7b49e88ac0d7e6959e65 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Tue, 18 Aug 2026 19:05:51 +0000 Subject: [PATCH] Updated mintlify pages - Updated skill.md Mintlify-Source: dashboard-editor --- skill.md | 35 ++++++++++++++++++++--------------- 1 file changed, 20 insertions(+), 15 deletions(-) diff --git a/skill.md b/skill.md index f7f49cb688..23726ac4ed 100644 --- a/skill.md +++ b/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 | `` | | Long code examples | `` | | User chooses one option | `` | @@ -172,6 +169,7 @@ The [components overview](https://mintlify.com/docs/components) organizes all co | API response fields | `` | **Callouts by severity:** + - `` - Supplementary info, safe to skip - `` - Helpful context such as permissions - `` - 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) \ No newline at end of file