SEO

SEO

This is a quote that stands out from the main content.

This is a quote that stands out from the main content.

Available Resources

What to include in AGENTS.md

Example AGENTS.md file

Make prompts specific and outcome-focused

Use broad prompts for maintenance tasks

Specify a domain name for multi-site organizations

What you can do with the agent

Where you can use the agent

• Overview

  • URL: https://dashboard.mintlify.com/

• agent endpoints

  • URL: /api/agent/create-agent-job

Next steps

Open the agent panel

• Overview
  • URL: https://dashboard.mintlify.com/

Connect your GitHub account

Connect repositories as context

Connect your Slack workspace

Use the agent in Slack

Update documentation

Best practices

Prerequisites

Configure suggestions

Review suggestions

Iterate on a prompt in a Slack thread

Start with the agent, finish manually

Update docs when merging feature changes

Generate release notes from a pull request

Address pull request review feedback

Generate code examples

Add images or files to your docs

Review existing content

Respond to user feedback

Automate with the API

What makes your documentation AI-native

Enable AI features

About the assistant

Configure the assistant

Customize assistant behavior

Manage billing

Connect apps

Assistant insights

Make content AI ingestible

Use the assistant

• https://mintlify.com/docs?assistant=open

  • URL: https://mintlify.com/docs?assistant=open

• https://mintlify.com/docs?assistant=explain webhooks

  • URL: https://mintlify.com/docs?assistant=explain%20webhooks

Troubleshooting

Add the Discord bot to your server

• Assistant
  • URL: https://dashboard.mintlify.com/products/assistant

Create an #ask-ai channel

Manage the Discord bot

Demo

Add an AsyncAPI specification file

Auto-populate websockets pages

Channel page

oneOf, anyOf, allOf keywords

x-hidden

x-excluded

Implementation

Setup

Enable authentication

Add an OpenAPI specification file

• Swagger's OpenAPI Guide

  • URL: https://swagger.io/docs/specification/v3_0/basic-structure/

• The OpenAPI specification Markdown sources

  • URL: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/

• Swagger Editor

  • URL: https://editor.swagger.io/

• The Mint CLI

  • URL: https://www.npmjs.com/package/mint

• API Keys: For header, query, or cookie-based keys.

  • URL: https://swagger.io/docs/specification/authentication/api-keys/

• Bearer: For JWT or OAuth tokens.

  • URL: https://swagger.io/docs/specification/authentication/bearer-authentication/

• Basic: For username and password.

  • URL: https://swagger.io/docs/specification/authentication/basic-authentication/

Customize your endpoint pages

Auto-populate API pages

Create MDX pages from your OpenAPI specification

Webhooks

Get started

Customize your playground

Further reading

• OpenAPI setup

  • URL: /api-playground/openapi-setup

• x-mint extension

  • URL: /api-playground/openapi-setup#customize-your-endpoint-pages

• MDX setup

  • URL: /api-playground/mdx-setup

• AsyncAPI setup

  • URL: /api-playground/asyncapi-setup

Single accordion

Accordion groups

Properties

• Font Awesome

  • URL: https://fontawesome.com/icons

• Lucide

  • URL: https://lucide.dev/icons

• Tabler

  • URL: https://tabler.io/icons

• SVGR converter

  • URL: https://react-svgr.com/playground/

Basic badge

Colors

Sizes

Shapes

Icons

Stroke variant

Disabled state

Inline usage

Combined properties

Properties

• Font Awesome

  • URL: https://fontawesome.com/icons

• Lucide

  • URL: https://lucide.dev/icons

• Tabler

  • URL: https://tabler.io/icons

• SVGR converter

  • URL: https://react-svgr.com/playground/

Properties

Language-specific banners

Basic card

Card variations

Group cards

Properties

• Font Awesome

  • URL: https://fontawesome.com/icons

• Lucide

  • URL: https://lucide.dev/icons

• Tabler

  • URL: https://tabler.io/icons

• SVGR converter

  • URL: https://react-svgr.com/playground/

Create code groups

Language dropdown

Compact variant

Table variant

Color formats

Theme-aware colors

Properties

Properties

RequestExample

ResponseExample

Properties

Parameter field

Response field

Captions

Hints

Properties

Inline icons

Properties

• Font Awesome icon

  • URL: https://fontawesome.com/icons

• Lucide icon

  • URL: https://lucide.dev/icons

• Tabler icon

  • URL: https://tabler.io/icons

Structure your content

Draw attention

Showcase AI prompts

Show and hide content

Document your API

Link to other pages

Add visual context

ELK layout support

Interactive controls

Properties

Syntax

Examples

Properties

• Font Awesome

  • URL: https://fontawesome.com/icons

• Lucide

  • URL: https://lucide.dev/icons

• Tabler

  • URL: https://tabler.io/icons

• SVGR converter

  • URL: https://react-svgr.com/playground/

Props

Steps properties

Individual step properties

• Font Awesome

  • URL: https://fontawesome.com/icons

• Lucide

  • URL: https://lucide.dev/icons

• Tabler

  • URL: https://tabler.io/icons

• SVGR converter

  • URL: https://react-svgr.com/playground/

Properties

Grid layout

Properties

Properties

Basic tree

Nested folders

Keyboard navigation

Properties

How to use

Props

Example

Table of contents behavior

Properties

Setting up your changelog

Customizing your changelog

• Slack

  • URL: https://slack.com/help/articles/218688467-Add-RSS-feeds-to-Slack

• Email

  • URL: https://zapier.com/apps/email/integrations/rss/1441/send-new-rss-feed-entries-via-email

• Readybot

  • URL: https://readybot.io

Adding code samples

Code block options

CodeBlock component

Supported file types

File organization

Images

Videos

iframes

Related resources

Lists

Tables

API key prefilling

Dynamic MDX content

Page visibility

OpenAPI content filtering

User data format

Logout behavior

Redirects

Check for broken links

How snippets work

Create snippets

Import snippets into pages

• React components
  • URL: /customize/react-components

Headers

Text formatting

Links

Blockquotes

Mathematical expressions

Line breaks and spacing

Best practices

Configuration

Parameters

Add your custom domain

• Custom domain setup
  • URL: https://dashboard.mintlify.com/settings/deployment/custom-domain

Configure your DNS

Set a canonical URL

Styling with Tailwind CSS

Custom CSS

Custom JavaScript

Google Fonts

Local fonts

Externally hosted fonts

Font configuration reference

Using React components

Importing components

Considerations

View audit logs

Export audit logs

• Audit log
  • URL: https://dashboard.mintlify.com/settings/organization/audit-logs

Add members to your organization

Configure a security contact

Set up SSO

JIT provisioning

Change or remove SSO provider

• Single Sign-On
  • URL: https://dashboard.mintlify.com/settings/organization/sso

Other providers

Configure authentication

Make pages public

Control access with groups

User data format

Installation

Configuration

Available CI checks

Set up a Cloudflare Worker

• Cloudflare dashboard

  • URL: https://dash.cloudflare.com/

• Delete DNS records

  • URL: https://developers.cloudflare.com/dns/manage-dns-records/how-to/create-dns-records/#delete-dns-records

Webflow custom routing

CSP directives

Domain whitelist

Example CSP configuration

Common configurations by proxy type

Troubleshooting

Manually trigger a deployment

Delete a deployment

Set up by hosting provider

• Cloudflare: Set up Cloudflare Workers for your domain to serve your documentation at the /docs subpath.

  • URL: /deploy/cloudflare

• AWS Route 53 and CloudFront: Deploy your documentation at the /docs subpath using AWS with Route 53 DNS and CloudFront CDN.

  • URL: /deploy/route53-cloudfront

• Vercel

  • URL: /deploy/vercel

• Custom reverse proxy

  • URL: /deploy/reverse-proxy

Prerequisites

• Network requirements

  • URL: #network-requirements

• https://leaves.mintlify.com

  • URL: https://leaves.mintlify.com

Step 1: Register the GitHub App

Step 2: Configure app permissions

Step 3: Generate and secure credentials

Step 4: Install the app

Step 5: Configure webhook URL

Share credentials with us

• https://your-github-server.com
  • URL: https://your-github-server.com

Mintlify connection

Test the integration

FAQ and Troubleshooting

Clone to your own repository

• Git Settings

  • URL: https://dashboard.mintlify.com/settings/deployment/git-settings

• Git Settings

  • URL: https://dashboard.mintlify.com/settings/deployment/git-settings

• Install the GitHub App

  • URL: #install-the-github-app

Install the GitHub App

Permissions

Manage repository access

Configure docs source

GitHub Enterprise with IP allowlists

Troubleshooting

Set up the connection

Create the webhook

Prerequisites

Configure monorepo deployment

Create preview deployments

• dashboard
  • URL: https://dashboard.mintlify.com/

Redeploy a preview

• dashboard
  • URL: https://dashboard.mintlify.com/

Preview widget

Restrict access to preview deployments

• Add-ons
  • URL: https://dashboard.mintlify.com/products/addons

Troubleshooting preview deployments

• dashboard
  • URL: https://dashboard.mintlify.com/

Choose your deployment approach

• Custom domain setup
  • URL: https://dashboard.mintlify.com/settings/deployment/custom-domain

Host at /docs subpath

• Custom domain setup
  • URL: https://dashboard.mintlify.com/settings/deployment/custom-domain

Custom subpath

Troubleshooting

Overview

Create CloudFront distribution

• CloudFront
  • URL: https://aws.amazon.com/cloudfront

Add default origin

• mintlify-landing-page.vercel.app
  • URL: https://mintlify-landing-page.vercel.app

Set behaviors

Preview distribution

Connect with Route53

• Route53
  • URL: https://aws.amazon.com/route53

vercel.json file

Configuration

• Custom domain setup

  • URL: https://dashboard.mintlify.com/settings/deployment/custom-domain

• Link: Add the following rewrites to your vercel.json file. Replace [subdomain] with your subdomain, which is found at the end of your dashboard URL. For example, dashboard.mintlify.com/your-organization/your-subdomain has a domain identifier of your-subdomain.

{
  "rewrites": [
    {
      "source": "/docs",
      "destination": "
    },
    {
      "source": "/docs/:match*",
      "destination": "https://[subdomain].mintlify.dev/docs/:match*"
    }
  ]
}

• URL: https://[subdomain].mintlify.dev/docs"

Required path allowlist

Header forwarding requirements

Testing your proxy setup

• Link: Test that ` returns a response.
  • URL: https://[yourdomain].com/.well-known/vercel/`

Branch-based collaboration

Recommended workflow

Preview deployments

Share editor links

Add a comment

Reply to a comment

Mention a teammate

Resolve a comment

Delete a comment

Brand your site

• theme
  • URL: /customize/themes

Customize colors and appearance

Set custom fonts

Configure header

Configure footer

Enhance content

Set up AI chat and search

Configure API specifications

Add analytics and integrations

What Git does for your docs

Key concepts

How the editor maps to Git

Key features

Get started

Publish and collaborate

Reference

Visual mode

Markdown mode

Open live preview

Live preview versus preview deployments

Supported file types

Add media to a page

Manage assets

Best practices

Add navigation elements

Organize into sections

Customize appearance

Navigate files

Create new pages

Edit content

Configure pages

Manage pages

Publishing workflows

Save changes

Resolve conflicts

Commit signing

Enable suggesting mode

Make a suggestion

Accept a suggestion

Reject a suggestion

Prerequisites

• Node.js

  • URL: https://nodejs.org/en

• Git

  • URL: https://git-scm.com/downloads

Install the CLI

Preview locally

Skip OpenAPI processing

Create a new project

Update the CLI

Additional commands

Formatting

Troubleshooting

Choose your migration path

Post-migration checklist

Hide a page

Hide a group of pages

Search, SEO, and AI indexing

Create a .mintignore file

• broken link checks
  • URL: /installation#find-broken-links

Default ignored patterns

Pattern syntax

Pages

Groups

Tabs

Anchors

Dropdowns

Products

OpenAPI

Versions

Languages

Nesting

Breadcrumbs

Interaction configuration

Page metadata

• Font Awesome icon

  • URL: https://fontawesome.com/icons

• Lucide icon

  • URL: https://lucide.dev/icons

• Tabler icon

  • URL: https://tabler.io/icons

Page mode

API pages

External links

Search engine optimization

Internal search keywords

Last modified timestamp

Setting up your docs.json

Reference

Examples

Upgrading from mint.json

Before you begin

Deploy your documentation site

View your deployed site

Make your first change

Next steps

Menu options

Enabling the contextual menu

Adding custom options

• Font Awesome icon

  • URL: https://fontawesome.com/icons

• Lucide icon

  • URL: https://lucide.dev/icons

• Tabler icon

  • URL: https://tabler.io/icons

llms.txt structure

llms-full.txt

Custom files

.md URL extension

Keyboard shortcut

About MCP servers

Access your MCP server

Content filtering and indexing

Use your MCP server

Use skill.md files with agents

skill.md structure

Custom skill.md files

Set up the Slack app

• Assistant
  • URL: https://dashboard.mintlify.com/products/assistant

Create an #ask-ai channel

Manage the Slack app

Rate limits

Suggested usage

Usage

Job details

Usage

Response

Usage

Filtering

Conversation data

Usage

Filtering

Response types

Integration with useChat

Rate limits

Endpoints

• Trigger update: Trigger an update of your site when desired.

  • URL: /api/update/trigger

• Get update status: Get the status of an update and other details about your docs.

  • URL: /api/update/status

• Create agent job: Create an agent job to automatically edit your documentation.

  • URL: /api/agent/create-agent-job

• Get agent job: Retrieve the details and status of a specific agent job.

  • URL: /api/agent/get-agent-job

• Get all agent jobs: Retrieve all agent jobs for a domain.

  • URL: /api/agent/get-all-jobs

• Generate assistant message: Embed the assistant, trained on your docs, into any application of your choosing.

  • URL: /api/assistant/create-assistant-message

• Search documentation: Search through your documentation.

  • URL: /api/assistant/search

• Get user feedback: Export user feedback from your documentation.

  • URL: /api/analytics/feedback

• Get assistant conversations: Export AI assistant conversation history.

  • URL: /api/analytics/assistant-conversations

• Trigger update

  • URL: /api/update/trigger

• Trigger update

  • URL: /api/update/trigger

• Generate assistant message

  • URL: /api/assistant/create-assistant-message

• Create agent job

  • URL: /api/agent/create-agent-job

• Get user feedback

  • URL: /api/analytics/feedback

Authentication

What is accessibility?

Getting started with accessibility

Structure your content

Write descriptive alt text

Design for readability

Make code examples accessible

Video and multimedia accessibility

Test your documentation

• NVDA (Windows)

  • URL: https://www.nvaccess.org/

• axe DevTools

  • URL: https://www.deque.com/axe/browser-extensions/

• Web Content Accessibility Guidelines

  • URL: https://www.w3.org/WAI/WCAG22/quickref/

Additional resources

• WebAIM

  • URL: https://webaim.org/

• The A11y Project

  • URL: https://www.a11yproject.com/

• W3C Web Accessibility Initiative (WAI)

  • URL: https://www.w3.org/WAI/

What you will build

Prerequisites

• Mintlify Pro or Enterprise plan

  • URL: https://mintlify.com/pricing

• Link: Your domain name, which appears at the end of your dashboard URL. For example, if your dashboard URL is your domain name isdomain-name`

  • URL: https://dashboard.mintlify.com/org-name/domain-name`,

• assistant API key

  • URL: https://dashboard.mintlify.com/settings/organization/api-keys

• API keys

  • URL: https://dashboard.mintlify.com/settings/organization/api-keys

Set up the example

Customization ideas

What you will build

Choose your platform

Branch naming conventions

Create a branch

Save changes on a branch

Switch branches

Merge branches

Getting started

CLAUDE.md template

Sample prompts

Extending Claude Code

How-to guide template

Tutorial template

Explanation template

Reference template

Related pages

Categorize using the Diátaxis framework

Picking a type

Writing for each type

Tips and tricks

• Understand your audience

  • URL: /guides/understand-your-audience

• content templates

  • URL: /guides/content-templates

Related pages

Use Cursor with Mintlify

Example project rule

Enhance with MCP server

Prerequisites

• Mintlify account

  • URL: https://dashboard.mintlify.com

• GitHub account

  • URL: https://github.com

• Node.js

  • URL: https://nodejs.org

• Astro

  • URL: https://docs.astro.build

Set up your project

How it works

Connect search and assistant

Next steps

• API references

  • URL: /api-playground/overview

• assistant

  • URL: /ai/assistant

• GitHub

  • URL: /deploy/github

• versions

  • URL: /organize/navigation#versions

Prerequisites

Migrate existing documentation

Plan your documentation structure

Set up your API reference

Set up the assistant

Set up versioning

Connect to your repository

Maintain your documentation

Next steps

GEO quickstart

GEO best practices

Mintlify configuration

Testing your documentation

Why Git for documentation?

New to Git?

Core Git concepts

How the web editor uses Git

Common workflows

Git best practices

Quantitative metrics

Qualitative feedback

• feedback

  • URL: /optimize/feedback

• Understand your audience

  • URL: /guides/understand-your-audience

Business alignment

Put analytics into action

Related pages

Topics

• Automate documentation updates: Tutorial that teaches how to set up automated documentation updates using the agent.

  • URL: /guides/automate-agent

• Build an in-app assistant: Tutorial that teaches how to add an AI chat bot in a React app to help users find answers from your documentation.

  • URL: /guides/assistant-embed

• Claude Code

  • URL: /guides/claude-code

• GEO: Best practices for optimizing your documentation for AI search and answer engines.

  • URL: /guides/geo

• Migrate from MDX to OAS: Move your API documentation from individual MDX pages to autogenerated pages from an OpenAPI specification.

  • URL: /guides/migrating-from-mdx

• Accessibility: Make your docs accessible to as many users as possible.

  • URL: /guides/accessibility

• Content types: Choose the right format for tutorials, how-tos, references, and explanations.

  • URL: /guides/content-types

• Content templates: Copy and modify templates for each content type.

  • URL: /guides/content-templates

• Improve your docs: Use data and feedback to continuously improve your documentation.

  • URL: /guides/improving-docs

• Internationalization: Set up multi-language documentation to reach global audiences.

  • URL: /guides/internationalization

• Linking: Create internal links, reference API endpoints, and maintain link integrity across your documentation.

  • URL: /guides/linking

• Maintenance: Keep your documentation accurate and up-to-date.

  • URL: /guides/maintenance

• Media: Add images, videos, and other media effectively while managing maintenance burden.

  • URL: /guides/media

• Organize navigation: Design information architecture that works for your users.

  • URL: /guides/navigation

• SEO: Optimize your docs for search engines.

  • URL: /guides/seo

• Style and tone: Write with a consistent voice.

  • URL: /guides/style-and-tone

• Understand your audience: Research and serve your users' needs and goals.

  • URL: /guides/understand-your-audience

• Git concepts: Learn the fundamentals of Git for documentation.

  • URL: /guides/git-concepts

• Branches: Use branches to manage documentation changes.

  • URL: /guides/branches

• Create developer documentation: Help your users get the most from your product or API with developer documentation that answers questions and gets people back to their main tasks.

  • URL: /guides/developer-documentation

• Create a knowledge base: Set up an internal knowledge base to consolidate information for your team, improve search, and reduce maintenance burden.

  • URL: /guides/knowledge-base

• Create a support center: Build a self-service support center that helps customers find answers, reduces ticket volume, and improves customer satisfaction.

  • URL: /guides/support-center

• Create a custom frontend: Use the Mintlify Astro integration to render your documentation with a fully custom frontend.

  • URL: /guides/custom-frontend

Where to start

File structure

Configure the language switcher

Maintain translations

SEO for multi-language sites

Best practices

• assistant

  • URL: /ai/assistant

• Slack

  • URL: /ai/slack-bot

• web editor

  • URL: /editor

• SSO or OAuth

  • URL: /deploy/authentication-setup

Prerequisites

Migrate existing content

Design the navigation structure

Set up authentication

Migrate your content

Set up the assistant

Enable team contributions

Establish maintenance workflows

Next steps

Internal links

• Quickstart guide

  • URL: /quickstart

• API overview

  • URL: /api-playground/overview

• Custom components

  • URL: /customize/react-components

Anchor links

• Customize your playground

  • URL: /api-playground/overview#customize-your-playground

• Cards properties

  • URL: /components/cards#properties

Link to API endpoints

Link to external pages

Best practices

Related resources

• Format text: Learn about Markdown formatting.

  • URL: /create/text

• Navigation: Configure your documentation structure.

  • URL: /organize/navigation

• Redirects: Set up redirects for moved content.

  • URL: /create/redirects

Automate what you can

• agent API

  • URL: /guides/automate-agent

• Vale

  • URL: http://Vale.sh

Set up a review process

Know when to rewrite

Wrong docs can be worse than no docs

When to use media

CLI migration

Manual migration steps

Navigation patterns

When to use individual MDX pages

Why is navigation important?

Map the foundation with stakeholders

Validate your assumptions

Identify common challenges

Iterate over time

Content basics

Technical SEO basics

• meta tags
  • URL: /optimize/seo

Page performance

Keyword research

• Google Keyword Planner
  • URL: https://ads.google.com/intl/en_us/home/tools/keyword-planner/

Writing principles

Common writing mistakes

Tips for enforcing style

• Microsoft Style Guide

  • URL: https://learn.microsoft.com/en-us/style-guide/welcome/

• Splunk Style Guide

  • URL: https://docs.splunk.com/Documentation/StyleGuide/current/StyleGuide/Howtouse

• Google Developer Documentation Style Guide

  • URL: https://developers.google.com/style

Related pages

• assistant

  • URL: /ai/assistant

• feedback widgets

  • URL: /optimize/feedback

• SSO or OAuth

  • URL: /deploy/authentication-setup

Prerequisites

Migrate existing content

Plan your support center structure

Write effective support content

Set up the assistant

Enable feedback collection

Set up analytics

Restrict content by customer segment

Maintain your support center

Next steps

Identify your primary audience

User research is key

Tips and tricks for understanding your audience

Use Windsurf with Mintlify

Example workspace rule

Working with Cascade

Enhance with MCP server

Get your project ID

• Clarity account
  • URL: https://clarity.microsoft.com/projects

How to Connect GA4 to Mintlify

Tracked events

How analytic integrations work

Supported platforms

Setup

Tracked events

Session recordings

Setup

Troubleshooting

Cookie consent and disabling telemetry

Prerequisites

• Mintlify documentation repository

  • URL: /quickstart

• automated code sample URL

  • URL: https://www.speakeasy.com/docs/code-samples/automated-code-sample-urls

Setting up the integration

Prerequisites

• Stainless
  • URL: https://app.stainless.com

Integrate with Stainless

Enabling support integrations

Filter by AI or human visitors

Filter time period

Visitors

Assistant

Searches

MCP searches

Feedback

Feedback types

Manage feedback

Use feedback data

Exporting a PDF

• General
  • URL: https://dashboard.mintlify.com/settings/deployment/general

Automatically generated meta tags

Global meta tags

Page-specific meta tags

Common meta tags reference

Sitemaps and robots.txt files

Disable indexing

SEO best practices

How to Use This Skill

Reference these resources when working with SEO.