Skip to main content
Mintlify automatically handles many SEO best practices, including:
  • Meta tag 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.

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

​
Set a canonical URL

If you’re using a custom domain, set the canonical meta tag to ensure search engines index your preferred domain. 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. 
"seo": {
    "metatags": {
        "canonical": "https://www.your-custom-domain-here.com"
    }
}

​
Page-specific meta tags

To set page-specific meta tags, add them to a page’s frontmatter. The following meta tags are supported at the page level:
  • title - Page title
  • description - Page description appears below the title on the page and in some search engine results
  • keywords - Comma-separated keywords
  • og:title - Open Graph title for social sharing
  • og:description - Open Graph 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
  • twitter:description - Twitter card 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:image": "link to your meta tag image"
"og:title": "Social media title"
keywords: ["keyword1", "keyword2"]
---
Meta tags with colons must be wrapped in quotes. The keywords field must be formatted as a YAML array.

​
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.
The og:image adds a background image that Mintlify automatically overlays with your logo, page title, and description when generating social media previews.
You can preview how your meta tags will 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. Only pages included in your docs.json are included by default. To include hidden links, add seo.indexing to your docs.json: 
"seo": {
    "indexing": "all"
}

​
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 will override the automatically generated file of the same name. If you delete a custom file, the default file will be used again.

​
Disabling indexing

If you want to stop a page from being indexed by search engines, you can include the following in the frontmatter of your 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"
    }
  }

​
SEO best practices

  • Use clear, descriptive page titles (50-60 characters)
  • Write compelling descriptions (150-160 characters)
  • Include relevant keywords
  • Make each page title and description unique
  • Use proper heading hierarchy (H1 → H2 → H3)
  • Write for humans first, search engines second
  • Include relevant keywords in headings and content
  • Keep URLs short, descriptive, and organized hierarchically
  • Break up long content with subheadings and lists
  • Link to related pages within your documentation
  • Use descriptive anchor text instead of “click here”
  • Create topic clusters by linking related concepts
  • Use the automatic cross-referencing features
  • Use descriptive file names for images
  • Always include alt text for accessibility and SEO
  • Optimize image file sizes for faster loading
  • Use relevant images that support your content