SEO

Mintlify automatically handles many SEO best practices, including:

• Meta tag generation
• Structured data (JSON-LD) generation
• Sitemap and robots.txt file generation
• Semantic HTML structure
• Mobile optimization

You can fully customize your site’s meta tags by adding the metatags field to your docs.json or a page’s frontmatter.

Automatically generated meta tags

Mintlify generates the following meta tags for every page. You can override these meta tags by specifying them in your docs.json or a page’s frontmatter.

Basic metadata:

• charset: utf-8 - Character encoding
• og:type: website - Open Graph type
• og:site_name - Your documentation site name
• twitter:card: summary_large_image - Twitter card type

Page-specific metadata:

• title - Page title, formatted as “Page Title - Site Name”
• og:title - Open Graph title, defaults to page title
• twitter:title - Twitter title, falls back to og:title, then page title
• description - Page description
• og:description - Open Graph description, falls back to page description
• twitter:description - Twitter description, falls back to og:description, then page description

URL and canonical:

• canonical - Automatically built from page URL
• og:url - Set to canonical URL

SEO and indexing:

• robots - Generated from page metadata
• noindex - Generated from page metadata
• keywords - Generated from page metadata

Images:

• og:image - Open Graph image, og:image:width set to 1200 and og:image:height 630
• twitter:image - Twitter image, twitter:image:width set to 1200 and twitter:image:height 630

Browser and app metadata:

• applicationName - Your documentation site name
• generator: Mintlify - Identifies the site generator as Mintlify
• apple-mobile-web-app-title - iOS home screen app name
• msapplication-TileColor - Windows tile color
• Favicons and icons from your config
• Sitemap reference link

Any meta tags in your docs.json seo.metatags configuration are also automatically injected into every page, such as google-site-verification for search console validation.

Structured data

Mintlify adds schema.org structured data to every indexable page as a JSON-LD script. This structured data helps search engines display rich results for your pages.

Each page emits a connected @graph of entities with stable @ids:

• Organization: The publisher of your site. Derived from your site name, logo, and site URL, or configured explicitly with seo.organization.
• WebSite: Your site.
• WebPage: The current page, including its description and modification dates.
• BreadcrumbList: The page’s location in your navigation hierarchy, generated from your docs.json navigation.
• The main content entity: TechArticle for documentation pages or APIReference for pages generated from API specifications (pages with api, openapi, or asyncapi frontmatter).

Mintlify generates the structured data from page frontmatter and docs.json configurations, including the page title, description, keywords, canonical URL, last updated date, site name, and logo. The structured data doesn’t include any fields without a corresponding value. Pages with noindex: true do not include structured data.

To change structured data, update the corresponding frontmatter fields or docs.json configurations. To control the publisher entity, including a stable @id, legal name, canonical logo, and sameAs profile links, set seo.organization in your docs.json.

OG images

Mintlify automatically generates an Open Graph (OG) image for every page. This image appears as the social preview when you share a link on social media platforms and messaging apps.

Default OG image properties:

• Width: 1200px
• Height: 630px
• Your site logo from the logo field in docs.json
• The page title from the page’s title frontmatter
• The page description from the page’s description frontmatter
• Your site’s primary color from the colors field in docs.json

Custom OG images

There are three ways to customize OG images, depending on the level of control you need.

Custom background image

To use a custom background image while keeping the auto-generated logo, title, and description overlay, set thumbnails.background in your docs.json.

"thumbnails": {
  "background": "/images/og-background.png"
}

See thumbnails for the full list of customization options.

Static OG image for all pages

To replace the auto-generated image entirely with a single static image across all pages, set og:image in your global meta tags.

"seo": {
  "metatags": {
    "og:image": "https://example.com/og-image.png"
  }
}

Static OG image for a specific page

To override the OG image for a single page, set og:image in that page’s frontmatter.

---
title: "Your page title"
description: "Your page description"
"og:image": "https://example.com/custom-og.png"
---

Global meta tags

To set default meta tags for all pages, add the metatags field to your docs.json.

"seo": {
    "metatags": {
        "og:image": "link to your default meta tag image"
    }
}

Verify site ownership

To verify your site with services like Google Search Console, Bing Webmaster Tools, or other search engines, add the verification meta tag to seo.metatags in your docs.json. Mintlify injects the tag into every page.

"seo": {
    "metatags": {
        "google-site-verification": "your_verification_token"
    }
}

Set a canonical URL

A canonical URL tells search engines which version of your documentation is the primary one. This improves SEO when your documentation is accessible from multiple URLs and prevents issues with duplicate content.

Global canonical

If you’re using a custom domain, set the canonical meta tag in your docs.json to ensure search engines index your preferred domain. Mintlify appends each page’s path to this base URL.

"seo": {
    "metatags": {
        "canonical": "https://www.your-custom-domain-here.com"
    }
}

Per-page canonical

To set a canonical URL for a specific page, add canonical to that page’s frontmatter. This overrides the global canonical and any auto-generated canonical for that page. This is useful for versioned documentation where you want older version pages to point to their equivalent on the latest version.

---
title: "My Page"
canonical: "https://docs.example.com/latest/my-page"
---

Page-specific meta tags

To set page-specific meta tags, add them to a page’s frontmatter.

Page-specific meta tags include:

• title - Page title
• description - Page description appears below the title on the page and in some search engine results
• canonical - Canonical URL for this page, overrides the auto-generated canonical
• keywords - Comma-separated keywords
• og:title - Open Graph title for social sharing
• og:description - Open Graph description, falls back to description
• og:image - Open Graph image URL
• og:url - Open Graph URL
• og:type - Open Graph type like “article” or “website”
• og:image:width - Open Graph image width
• og:image:height - Open Graph image height
• twitter:title - Twitter card title, falls back to og:title, then title
• twitter:description - Twitter card description, falls back to og:description, then description
• twitter:image - Twitter card image
• twitter:card - Twitter card type like summary or summary_large_image
• twitter:site - Twitter site handle
• twitter:image:width - Twitter image width
• twitter:image:height - Twitter image height
• noindex - Set to true to prevent search engine indexing
• robots - Robots meta tag value

---
title: "Your example page title"
description: "Page-specific description"
"og:title": "Social media title"
"og:description": "Custom description for social sharing"
"og:image": "link to your meta tag image"
"twitter:title": "Twitter-specific title"
keywords: ["keyword1", "keyword2"]
---

Common meta tags reference

Below is a comprehensive list of meta tags you can add to your docs.json. These meta tags help improve your site’s SEO, social sharing, and browser compatibility.

You can preview how your meta tags appear on different platforms using metatags.io.

"seo": {
    "metatags": {
      "robots": "noindex",
      "charset": "UTF-8",
      "viewport": "width=device-width, initial-scale=1.0",
      "description": "Page description",
      "keywords": "keyword1, keyword2, keyword3",
      "author": "Author Name",
      "robots": "index, follow",
      "googlebot": "index, follow",
      "google": "notranslate",
      "google-site-verification": "verification_token",
      "generator": "Mintlify",
      "theme-color": "#000000",
      "color-scheme": "light dark",
      "canonical": "https://your-custom-domain-here.com",
      "format-detection": "telephone=no",
      "referrer": "origin",
      "refresh": "30",
      "rating": "general",
      "revisit-after": "7 days",
      "language": "en",
      "copyright": "Copyright 2024",
      "reply-to": "email@example.com",
      "distribution": "global",
      "coverage": "Worldwide",
      "category": "Technology",
      "target": "all",
      "HandheldFriendly": "True",
      "MobileOptimized": "320",
      "apple-mobile-web-app-capable": "yes",
      "apple-mobile-web-app-status-bar-style": "black",
      "apple-mobile-web-app-title": "App Title",
      "application-name": "App Name",
      "msapplication-TileColor": "#000000",
      "msapplication-TileImage": "path/to/tile.png",
      "msapplication-config": "path/to/browserconfig.xml",
      "og:title": "Open Graph Title",
      "og:type": "website",
      "og:url": "https://example.com",
      "og:image": "https://example.com/image.jpg",
      "og:description": "Open Graph Description",
      "og:site_name": "Site Name",
      "og:locale": "en_US",
      "og:video": "https://example.com/video.mp4",
      "og:audio": "https://example.com/audio.mp3",
      "twitter:card": "summary",
      "twitter:site": "@username",
      "twitter:creator": "@username",
      "twitter:title": "Twitter Title",
      "twitter:description": "Twitter Description",
      "twitter:image": "https://example.com/image.jpg",
      "twitter:image:alt": "Image Description",
      "twitter:player": "https://example.com/player",
      "twitter:player:width": "480",
      "twitter:player:height": "480",
      "twitter:app:name:iphone": "App Name",
      "twitter:app:id:iphone": "12345",
      "twitter:app:url:iphone": "app://",
      "article:published_time": "2024-01-01T00:00:00+00:00",
      "article:modified_time": "2024-01-02T00:00:00+00:00",
      "article:expiration_time": "2024-12-31T00:00:00+00:00",
      "article:author": "Author Name",
      "article:section": "Technology",
      "article:tag": "tag1, tag2, tag3",
      "book:author": "Author Name",
      "book:isbn": "1234567890",
      "book:release_date": "2024-01-01",
      "book:tag": "tag1, tag2, tag3",
      "profile:first_name": "John",
      "profile:last_name": "Doe",
      "profile:username": "johndoe",
      "profile:gender": "male",
      "music:duration": "205",
      "music:album": "Album Name",
      "music:album:disc": "1",
      "music:album:track": "1",
      "music:musician": "Artist Name",
      "music:song": "Song Name",
      "music:song:disc": "1",
      "music:song:track": "1",
      "video:actor": "Actor Name",
      "video:actor:role": "Role Name",
      "video:director": "Director Name",
      "video:writer": "Writer Name",
      "video:duration": "120",
      "video:release_date": "2024-01-01",
      "video:tag": "tag1, tag2, tag3",
      "video:series": "Series Name"
  }
}

Sitemaps and robots.txt files

Mintlify automatically generates a sitemap.xml file and a robots.txt file. You can view your sitemap by appending /sitemap.xml to your documentation site’s URL.

By default, Mintlify indexes only the pages you include in your docs.json navigation. It excludes hidden pages that exist in your repository but are not listed in your navigation from:

• Search engine sitemaps
• Internal documentation search
• AI assistant context
• MCP server search results

To include hidden pages in search indexing, add seo.indexing to your docs.json:

"seo": {
    "indexing": "all"
}

To include only the pages under a specific hidden tab or group, set searchable: true on that tab or group. See Search, SEO, and AI indexing for details.

Trailing slash URLs

If your hosting setup serves every page with a trailing slash (for example, /quickstart/ instead of /quickstart), enable seo.trailingSlash in your docs.json so the URLs Mintlify emits for SEO match.

"seo": {
    "trailingSlash": true
}

Content-Signal directives

The auto-generated robots.txt includes Content-Signal directives that tell AI crawlers how they can use your documentation. These signals follow the Cloudflare Content Signals Policy and apply to all user agents:

User-agent: *
Content-Signal: ai-train=yes, search=yes, ai-input=yes

The default signals opt your documentation in to:

• ai-train=yes—Training AI models.
• search=yes—Building search indexes.
• ai-input=yes—Generating AI answers, including in retrieval-augmented generation and AI assistants.

These defaults help AI tools like ChatGPT, Claude, and Perplexity discover and cite your documentation. To change the signals, add a custom robots.txt at the root of your project. Mintlify serves custom files as-is, without the default Content-Signal directives.

Custom sitemaps and robots.txt files

To add a custom sitemap.xml or robots.txt file, create a sitemap.xml or robots.txt file at the root of your project. Adding a custom file overrides the automatically generated file of the same name. If you delete a custom file, the default file automatically applies again.

Disable indexing

To prevent search engines from indexing a page, add noindex: true to the frontmatter of the page.

---
noindex: true
---

You can also specify noindex for all pages in your docs by setting the metatags.robots field to "noindex" in your docs.json:

"seo": {
    "metatags": {
      "robots": "noindex"
    }
  }

Disable indexing for the entire project

To hide your entire deployment from search engines while keeping it publicly accessible, enable Don’t index project on the Add-ons page of your dashboard.

When enabled, your site:

• Renders every page with noindex, nofollow robots meta tags.
• Returns an empty sitemap.xml.
• Returns 404 for llms.txt and llms-full.txt.
• Clears your search index so pages no longer appear in internal search, the assistant, or your search MCP server.
• Serves a site-wide disallow robots.txt:

Disable indexing when you want to keep a deployment online for internal review, staging, or limited sharing, but you do not want the site to appear in public search results or for AI tools to use as training or retrieval data.

This setting works alongside other indexing controls:

• Per-page noindex: Page-level noindex: true in frontmatter continues to apply when the project-level setting is off. Project-level settings override per-page settings when enabled.
• Custom robots.txt: If you have a custom robots.txt at the root of your project, Mintlify serves it unchanged. Project-level settings do not replace custom robots.txt files, so you must update or remove custom files for crawler rules to match.

SEO best practices