> ## Documentation Index
> Fetch the complete documentation index at: https://www.mintlify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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
* 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.
## 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`.
```json Example docs.json theme={null}
"thumbnails": {
"background": "/images/og-background.png"
}
```
See [`thumbnails`](/organize/settings-appearance#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.
```json Example docs.json theme={null}
"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.
```yaml Example frontmatter theme={null}
---
title: "Your page title"
description: "Your page description"
"og:image": "https://example.com/custom-og.png"
---
```
Setting `og:image` in meta tags, globally or per-page, replaces the auto-generated social preview with a static image. If you want Mintlify to automatically overlay your logo, page title, and description on a custom background, use [`thumbnails.background`](/organize/settings-appearance#param-thumbnails-background) instead.
## Global meta tags
To set default meta tags for all pages, add the `metatags` field to your `docs.json`.
```json theme={null}
"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.
```json theme={null}
"seo": {
"metatags": {
"canonical": "https://www.your-custom-domain-here.com"
}
}
```
Always verify canonical URL behavior on your deployed site. Local builds add `/src/_props` to URLs as an artifact that are not part of the canonical URL.
## 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
* `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
Twitter meta tags automatically inherit from their Open Graph equivalents. For example, if you set `og:title` but not `twitter:title`, the Twitter card uses your `og:title` value. Set `twitter:title` or `twitter:description` explicitly only when you want different text on Twitter than on other platforms.
```mdx theme={null}
---
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"]
---
```
You must wrap meta tags with colons in quotes. For example, `og:title: "Social media title"`.
You must format the `keywords` field as a YAML array. For example, `keywords: ["keyword1", "keyword2", "keyword3"]`.
## 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.
Setting `og:image` in meta tags replaces the auto-generated social preview with a static image. If you want a custom **background image** that Mintlify automatically overlays with your logo, page title, and description, use [`thumbnails.background`](/organize/settings-reference#thumbnails-background) in your `docs.json` instead.
You can preview how your meta tags appear on different platforms using [metatags.io](https://metatags.io/).
```json expandable theme={null}
"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](/organize/hidden-pages) that exist in your repository but are not listed in your navigation from:
* Search engine sitemaps
* Internal documentation search
* [AI assistant](/assistant/index) context
* [MCP server](/ai/model-context-protocol) search results
To include hidden pages in search indexing, add `seo.indexing` to your `docs.json`:
```json theme={null}
"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](/organize/hidden-pages#search-seo-and-ai-indexing) for details.
For documentation sites that require authentication, sitemaps and `robots.txt` files also require authenticating to access. Sitemaps exclude pages that belong to [user groups](/deploy/authentication-setup#control-access-with-groups).
### 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.
If your custom `robots.txt` blocks AI user agents like `GPTBot`, `ClaudeBot`, or `PerplexityBot`, AI tools cannot crawl your documentation and cannot cite it in answers. See [Allow AI agents in robots.txt](/guides/geo#allow-ai-agents-in-robotstxt) for details.
## Disable indexing
To prevent search engines from indexing a page, add `noindex: true` to the [frontmatter](/organize/pages) of the page.
```yaml theme={null}
---
noindex: true
---
```
Pages with `hidden: true` in their frontmatter are automatically treated as `noindex: true`. See [Hidden pages](/organize/hidden-pages) for more details.
You can also specify `noindex` for all pages in your docs by setting the `metatags.robots` field to `"noindex"` in your `docs.json`:
```json theme={null}
"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 filenames for images
* Always include alt text for accessibility and SEO
* Optimize image file sizes for faster loading
* Use relevant images that support your content
## Related topics
- [Pages](/docs/organize/pages.md)
- [React](/docs/customize/react-components.md)
- [Assistant](/docs/assistant/index.md)