mintlify__docs/guides/seo.mdx

---
title: "How to improve documentation SEO"
sidebarTitle: "SEO"
description: "Improve your documentation's search engine rankings with page titles, keyword research, internal linking, and technical SEO techniques."
keywords: ["documentation SEO", "search engine optimization", "keyword research", "technical SEO", "meta descriptions"]
---

Search engines are one of the most reliable ways users find documentation. When someone searches "how to set up authentication with [your product]," well-optimized documentation puts your content at the top of results instead of a Stack Overflow post or a competitor's page.

This guide covers the techniques that have the most impact on documentation SEO, from writing better page titles to building a maintainable internal linking strategy.

## Write page titles and descriptions that rank

Page titles are the single most important on-page SEO signal. They tell search engines—and users—exactly what a page covers.

### Titles (50-60 characters)

Write titles that match how users search, not how your product UI labels things. "Authentication" is a product label. "How to authenticate API requests" is a search query.

- Match the user's intent: use "how to," "guide," or "reference" where appropriate
- Include the primary keyword near the start
- Make each title unique—duplicate titles confuse search engines

### Descriptions (130-160 characters)

The description appears below your page title in search results. A good description improves click-through rates even when rankings are equal.

- Summarize what users can accomplish, not just what the page covers
- Include the primary keyword naturally
- Write in active voice: "Learn how to configure" rather than "This page explains"

Mintlify generates meta tags automatically from your `title` and `description` frontmatter. For advanced configuration like Open Graph images, canonical URLs, or custom robots directives, see the [SEO configuration reference](/optimize/seo).

## Do keyword research for your docs

Keyword research helps you understand what users actually type when they're looking for what your documentation covers.

**Start with your own data:** If you have [Google Search Console](https://search.google.com/search-console) connected to your docs, look at the "Search results" report. Your best optimization targets are the queries users are already finding you for and the ones you're appearing for but not ranking well on.

**Find related queries:** Free tools like [Google Keyword Planner](https://ads.google.com/intl/en_us/home/tools/keyword-planner/) and [Ahrefs Free Keyword Generator](https://ahrefs.com/keyword-generator) show you how many people search for a given phrase and suggest related terms.

### Apply keywords where they belong
- The page title and description (highest impact)
- H2 and H3 headings
- The first paragraph of the page
- Alt text for relevant images

Don't repeat keywords mechanically. Documentation should read naturally. If a heading sounds forced, the keyword isn't right for that section.

## Structure content with headings search engines can parse

Heading structure serves two purposes: it helps users scan the page and it tells search engines how topics relate to each other.

Mintlify creates the H1 for each page automatically from the `title:` property in your frontmatter. Never add a manual H1 inside the page body. Structure everything else as H2 and below:

```mdx
## Main section (H2)

### Subsection (H3)

#### Detail (H4, use sparingly)
```

**Write headings as questions or intent phrases.** Compare:

| Weak heading | Stronger heading |
|---|---|
| Authentication | How authentication works |
| Rate limits | Understanding API rate limits |
| Configuration | How to configure your integration |

Headings written as questions are more likely to appear in Google's People Also Ask boxes, which appear before organic results and generate clicks even from lower-ranked pages.

## Build internal links between related pages

Internal links do two things for SEO: they help search engines discover and understand your content, and they pass ranking authority between pages.

**Link to related concepts** from within your content. When you explain a concept that depends on another, link to it with descriptive anchor text:

```mdx
<!-- Good -->
Learn how to [configure your sitemap](/optimize/seo#sitemaps-and-robots-txt-files).

<!-- Not helpful for SEO -->
[Click here](/optimize/seo) to learn more.
```

**Look for orphan pages:** Pages with no internal links pointing to them are orphans. Search engines are less likely to discover and rank pages that aren't linked from anywhere. A monthly review of your navigation helps catch these.

**Create topic clusters:** Group related pages with links between them. A getting started page should link to the authentication reference, which links to the API keys page, which links back to the overview. This signals to search engines that these pages cover a coherent topic.

## Add alt text to images

Alt text serves both accessibility and SEO. Search engines can't interpret images, so alt text is how image content contributes to your page's relevance signals.

Write alt text that describes what the image shows in context:

```mdx
<!-- Specific and descriptive -->
![API authentication flow showing the token exchange between client, auth server, and API](/images/auth-flow.png)

<!-- Too generic -->
![Diagram](/images/auth-flow.png)
```

Include relevant keywords in alt text where they fit naturally. Don't add keywords that don't describe the image.

## Technical SEO Mintlify handles automatically

Mintlify takes care of several technical SEO foundations:

- **Sitemap generation:** A `sitemap.xml` is automatically generated and updated. You can submit it directly to [Google Search Console](https://search.google.com/search-console) to speed up indexing.
- **Semantic HTML:** Mintlify renders pages with proper HTML structure, including heading hierarchy and navigation landmarks.
- **Mobile optimization:** Documentation is responsive by default.
- **Canonical URLs:** Canonical tags are automatically generated to prevent duplicate content issues.

For anything you need to configure manually—global meta tags, per-page overrides, custom sitemaps, indexing rules—see the [SEO configuration reference](/optimize/seo).

## Keep documentation current

Search engines treat content freshness as a ranking signal, especially for pages covering topics that change over time (API references, configuration guides, integration instructions).

A practical approach:

- When you ship a feature update, update the corresponding docs in the same pull request
- Review high-traffic pages quarterly for accuracy
- Check for broken links with `mint broken-links` before publishing

<Tip>
  Use [automations](/automations) to automate SEO maintenance tasks.
</Tip>

Stale documentation creates a second problem beyond SEO: if users find your page through search but the information is wrong, they lose trust in your docs.

## Monitor your search performance

Set up [Google Search Console](https://search.google.com/search-console) for your documentation domain. It shows you:

- **Impressions and clicks:** Which pages appear in search results and how often users click them
- **Average position:** Where your pages rank for specific queries
- **Queries:** The exact search terms driving traffic, useful for finding new optimization opportunities

Check it monthly and prioritize pages with high impressions but low clicks (your title or description isn't compelling) and pages with low positions for important queries (content depth may need improvement).

## Frequently asked questions

<AccordionGroup>
<Accordion title="How long should a documentation page be for SEO?">
There's no universal ideal length. Pages should be long enough to comprehensively cover the topic and short enough to stay focused. A getting started guide might be 800 words. A detailed API reference might be 3,000. What matters is that users can accomplish their goal from the page—if they need to leave to find additional information, the page is probably too thin. Generally, pages under 300 words struggle to rank for competitive queries because they don't demonstrate topical depth.
</Accordion>

<Accordion title="Does documentation SEO work differently from blog SEO?">
The core principles are the same. Relevant titles, well-structured content, and internal links are all important. But documentation has some distinct advantages. Documentation pages often target highly specific long-tail queries ("how to configure OAuth with [product]") where there's less competition than general blog topics. They also accumulate links naturally when developers share them in Stack Overflow answers, GitHub issues, and community forums. Focus on specificity and accuracy over volume.
</Accordion>

<Accordion title="How do I submit my documentation sitemap to Google?">
In [Google Search Console](https://search.google.com/search-console), go to **Sitemaps** in the left sidebar and enter your sitemap URL. For Mintlify docs, your sitemap is at `https://your-docs-domain.com/sitemap.xml`. Submitting your sitemap doesn't guarantee immediate indexing, but it speeds up discovery and helps Google understand your site structure.
</Accordion>

<Accordion title="How often should I update documentation for SEO?">
Update documentation whenever the product changes—accuracy is the most important signal. For SEO specifically, pages untouched for over a year may benefit from a review to add missing information, update examples, and expand thin sections. Use Google Search Console to prioritize: pages losing traffic or dropping in position are candidates for a refresh.
</Accordion>

<Accordion title="What's the difference between SEO and GEO?">
SEO (Search Engine Optimization) focuses on ranking in traditional search engines like Google and Bing. GEO (Generative Engine Optimization) focuses on earning citations from AI-powered tools like ChatGPT, Perplexity, and Google AI Overviews. The fundamentals overlap—accurate, well-structured content performs well in both—but GEO has some additional practices around formatting for AI parsing. See the [GEO guide](/guides/geo) for details.
</Accordion>

<Accordion title="Does Mintlify automatically handle documentation SEO?">
Mintlify handles the technical foundation: sitemap generation, semantic HTML, canonical tags, meta tag generation, and mobile optimization. What Mintlify can't do for you is write better titles, do keyword research, build internal links, or expand thin content—those require editorial decisions. The [SEO configuration reference](/optimize/seo) covers everything you can control through `docs.json` and page frontmatter.
</Accordion>
</AccordionGroup>