SEO

Configure meta tags, Open Graph properties, canonical URLs, and page-level SEO settings to improve your documentation's search engine ranking.

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.

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.

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.

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

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"
---

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"
    }
}

To apply different meta tags to a subset of pages, such as versioned docs or a specific product area, add seo.paths to your docs.json. Each entry targets a folder path relative to the docs root and applies its tags to every page under that folder.

"seo": {
    "metatags": {
        "og:image": "https://example.com/og/default.png"
    },
    "paths": [
        {
            "path": "guides/v1",
            "metatags": {
                "robots": "noindex"
            }
        },
        {
            "path": "guides/v2",
            "metatags": {
                "og:image": "https://example.com/og/v2.png"
            }
        }
    ]
}

Folder tags override seo.metatags for the same key, longer paths override shorter ones, and page frontmatter overrides both. See seo.paths for path rules and exceptions.

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"
    }
}

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"
---

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"]
---

Frontmatter can also override any custom meta tag declared in your docs.json under seo.metatags or a matching seo.paths entry. Set the same key to a non-empty string to replace the site-wide or folder value on that page. Frontmatter can't add custom meta tags that your config doesn't declare, and Mintlify ignores non-string values.

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"
  }
}

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. Hidden pages include pages missing from your navigation, pages under a hidden tab or group, and pages with hidden: true in their frontmatter. Mintlify excludes hidden pages from the following locations:

• 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.

If your hosting setup serves every page with a trailing slash, such as /quickstart/ instead of /quickstart, enable seo.trailingSlash in your docs.json. This makes the URLs Mintlify emits for SEO match.

"seo": {
    "trailingSlash": true
}

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.

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

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"
    }
  }

To hide your entire project from search engines while keeping it publicly accessible, enable Don't index project on the General 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, including at /.well-known/llms.txt.

• Removes your pages from Mintlify Index, so coding agents can no longer retrieve your content there.

• Serves a site-wide disallow robots.txt:

  User-agent: *
  Content-Signal: ai-train=no, search=no, ai-input=no
  Disallow: /

Your in-product search, assistant, and MCP server keep working. To remove pages from those, use noindex: true or searchable: false on individual pages.

Disable indexing when you need to keep a project online for internal review, staging, or limited sharing. This prevents the site from appearing in public search results and prevents AI tools from using it 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 and search
• How to improve documentation SEO
• docs.json schema reference