Skip to main content
Mintlify automatically handles many SEO best practices, including:
  • Meta tag generation: Automatic creation of essential meta tags from page frontmatter
  • Sitemap and robots.txt file generation: Automatic generation and updates on deployment
  • Semantic HTML structure: Proper heading hierarchy and semantic elements
  • Mobile optimization: Responsive design that works across all devices
  • Fast page loads: Optimized assets and efficient rendering
  • Clean URLs: SEO-friendly URL structure based on file paths
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. Why canonical URLs matter:
  • Prevents duplicate content issues when docs are accessible from multiple URLs
  • Consolidates ranking signals to your preferred domain
  • Helps search engines understand which version to index
  • Essential when using custom domains, subdomains, or CDN URLs
"seo": {
    "metatags": {
        "canonical": "https://www.your-custom-domain-here.com"
    }
}
The canonical URL should be the primary domain where you want search traffic directed. Don’t include the page path—Mintlify automatically appends it.

​
Page-specific meta tags

To set page-specific meta tags, add them to a page’s frontmatter. 
---
title: "Your example page title"
"og:image": "link to your meta tag image"
---
Meta tags with colons must be wrapped in quotes.

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

​
Sitemap configuration

Only pages included in your docs.json navigation are included by default. To include hidden pages, add seo.indexing to your docs.json: 
"seo": {
    "indexing": "all"
}
Indexing options:
  • "navigable" (default): Only pages in your navigation structure
  • "all": All pages, including hidden pages and those not in navigation

​
Submitting your sitemap

After deploying your documentation:
  1. Visit Google Search Console
  2. Add and verify your property (domain or URL prefix)
  3. Navigate to “Sitemaps” in the left sidebar
  4. Enter your sitemap URL: https://yourdomain.com/sitemap.xml
  5. Click “Submit”
Google will begin crawling and indexing your pages. This process can take a few days to several weeks.

​
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. When to use custom files:
  • You need specific sitemap formatting for third-party tools
  • You want to exclude specific user agents in robots.txt
  • You need multiple sitemaps for different content types
  • You want to add custom crawl delays or directives

​
Disabling indexing

Control which pages search engines can index using the noindex directive.

​
Per-page noindex

To prevent a specific page from being indexed, add noindex to the page’s frontmatter: 
---
title: "Internal documentation"
noindex: true
---
Common use cases:
  • Internal or draft documentation
  • Deprecated pages that should remain accessible but not searchable
  • Staging or preview environments
  • Pages with duplicate content

​
Site-wide noindex

To prevent all pages from being indexed, set the metatags.robots field in your docs.json: 
"seo": {
    "metatags": {
      "robots": "noindex"
    }
  }
Use site-wide noindex carefully. This prevents all pages from appearing in search results, which is typically only appropriate for staging environments or internal documentation.

​
Other robots directives

You can use additional robots meta tag directives: 
"seo": {
    "metatags": {
      "robots": "noindex, nofollow",  // Don't index and don't follow links
      "googlebot": "noindex"           // Specific to Google's crawler
    }
  }
Available directives:
  • index / noindex: Allow or prevent indexing
  • follow / nofollow: Allow or prevent following links
  • noarchive: Prevent cached copies in search results
  • nosnippet: Prevent text snippets in search results
  • noimageindex: Prevent images from being indexed

​
SEO best practices

  • Use clear, descriptive page titles (50-60 characters)
  • Write compelling descriptions (150-160 characters)
  • Include relevant keywords naturally
  • Make each page title and description unique
  • Place primary keywords near the beginning
  • Match user search intent
  • Avoid keyword stuffing or clickbait
  • 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
  • Use bullet points for scannable information
  • Add code examples and practical demonstrations
  • Include visual aids (diagrams, screenshots, videos)
  • Link to related pages within your documentation
  • Use descriptive anchor text instead of “click here”
  • Create topic clusters by linking related concepts
  • Ensure all important pages are linked from at least one other page
  • Add contextual links within body content
  • Use relative paths for internal links
  • Fix broken links promptly
  • Use descriptive file names: oauth-flow-diagram.png not image1.png
  • Always include alt text for accessibility and SEO
  • Keep alt text under 125 characters
  • Optimize image file sizes for faster loading
  • Use modern formats (WebP, AVIF) when possible
  • Implement lazy loading for images below the fold
  • Use relevant images that support your content
  • Compress images without sacrificing quality
  • Ensure fast page load times (under 3 seconds)
  • Optimize Core Web Vitals (LCP, FID, CLS)
  • Use semantic HTML elements
  • Implement structured data (schema markup)
  • Ensure mobile responsiveness
  • Enable HTTPS for security
  • Minimize JavaScript and CSS
  • Use a CDN for faster content delivery
  • Update outdated content regularly
  • Add publication and update dates where relevant
  • Refresh underperforming pages
  • Remove or redirect obsolete pages
  • Monitor for broken links and fix them
  • Keep code examples current with latest versions
  • Add new content targeting high-value keywords

​
Advanced SEO techniques

​
Schema markup

Add structured data to help search engines understand your content: 
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "API Authentication Guide",
  "description": "Learn how to authenticate API requests",
  "author": {
    "@type": "Organization",
    "name": "Your Company"
  },
  "datePublished": "2024-01-15",
  "dateModified": "2024-11-20"
}
</script>

​
Open Graph tags

Optimize social media sharing with Open Graph tags: 
"seo": {
  "metatags": {
    "og:title": "API Authentication Guide",
    "og:description": "Learn how to authenticate API requests using OAuth 2.0",
    "og:image": "https://yourdomain.com/images/auth-guide.png",
    "og:type": "article",
    "twitter:card": "summary_large_image"
  }
}

​
International SEO

For multi-language documentation, use hreflang tags: 
"seo": {
  "metatags": {
    "hreflang": "en-us"
  }
}
Configure language alternatives in your navigation structure using the languages feature. Build authority through quality backlinks:
  • Create valuable, shareable content
  • Contribute to developer communities (Stack Overflow, Reddit, Dev.to)
  • Write guest posts on relevant blogs
  • Get listed in developer resource directories
  • Engage with your community on social media
  • Create tools or resources others want to link to