Search optimization

Improve discoverability of your documentation through better search results

Mintlify provides built-in search functionality. This guide helps you optimize your content for better search results.

How search works

Mintlify’s search indexes:

• Page titles and descriptions
• Headings (H1, H2, H3)
• Body content
• Code block titles
• Component content

Search results are ranked by:

1. Relevance: How well the query matches the content
2. Title matches: Exact matches in titles rank higher
3. Heading matches: Matches in headings rank higher than body text
4. Recency: Recently updated pages may rank higher

Optimize page metadata

Write descriptive titles

Good titles:

• “Install the CLI”
• “Configure authentication”
• “Troubleshoot build errors”

Poor titles:

• “Getting Started” (too generic)
• “Page 1” (not descriptive)
• “CLI” (too short)

Add meaningful descriptions

Descriptions appear in search results and help users decide if a page is relevant.

Good description:

---
title: Install the CLI
description: Install the Mintlify CLI to preview and develop your documentation locally
---

Poor description:

---
title: Install the CLI
description: Learn about the CLI
---

Use relevant keywords

Add keywords to frontmatter for better discoverability:

---
title: Install the CLI
description: Install the Mintlify CLI to preview and develop your documentation locally
keywords: ["CLI", "installation", "local development", "preview", "npm"]
---

Structure content for search

Use clear headings

Break content into sections with descriptive headings:

## Install on macOS

Instructions for macOS...

## Install on Windows

Instructions for Windows...

## Install on Linux

Instructions for Linux...

This helps users find specific sections through search.

Front-load important information

Place key information early in your content:

Good:

The API key is required for authentication. Generate one in your dashboard settings.

Poor:

To use our API, you'll need several things. First, make sure you have an account. Then, navigate to the settings. Finally, you can generate an API key for authentication.

Use natural language

Write how users search. If users search “how to deploy”, use that phrase in your content:

## How to deploy your documentation

To deploy your documentation, push changes to your connected repository...

Improve content discoverability

Create overview pages

Add overview pages for major sections:

---
title: API reference overview
description: Complete reference for all API endpoints, authentication, and error handling
---

Our API provides programmatic access to your documentation. This section covers:

- [Authentication](/api/authentication) - API keys and security
- [Endpoints](/api/endpoints) - Available API operations
- [Rate limits](/api/rate-limits) - Usage quotas and limits
- [Error handling](/api/errors) - Common errors and solutions

Add cross-references

Link related pages to improve navigation:

<Info>
  New to Mintlify? Start with the [quickstart guide](/quickstart) before configuring advanced features.
</Info>

Use synonyms

Include alternative terms users might search for:

## Environment variables (env vars)

Configure environment variables to customize your deployment...

Optimize for common queries

Answer questions directly

Structure content to answer common questions:

## How do I add a custom domain?

To add a custom domain:

1. Go to your dashboard settings
2. Click "Custom domain"
3. Enter your domain name
4. Update your DNS records

Include troubleshooting

Add troubleshooting sections for common issues:

## Troubleshooting

### Images not loading

If images don't appear:
- Verify the image path is correct
- Check that images are committed to Git
- Ensure file names don't contain spaces

Document error messages

Include actual error messages users might search for:

## "Module not found" error

If you see `Error: Cannot find module 'mintlify'`:

1. Reinstall the CLI: `npm install -g mintlify`
2. Clear npm cache: `npm cache clean --force`
3. Try again

Technical optimization

Keep pages focused

Each page should cover one topic thoroughly rather than multiple topics superficially.

Good structure:

/authentication/overview
/authentication/api-keys
/authentication/oauth
/authentication/jwt

Poor structure:

/authentication (covers everything)

Use descriptive URLs

Page paths affect search relevance:

Good:

/api-playground/openapi-setup
/deploy/custom-domain
/troubleshooting/build-errors

Poor:

/page1
/docs/item
/misc/other

Avoid duplicate content

Don’t repeat the same information across multiple pages. Instead:

• Create one authoritative page
• Link to it from other pages
• Use snippets for shared content

Search best practices

Include code examples

Code examples improve search results for technical queries:

## Install with npm

```bash
npm install -g mintlify

Install with pnpm

pnpm add -g mintlify

### Add alt text to images

Alt text is indexed by search:

```mdx
![Dashboard showing deployment status with green checkmark](/images/deployment-success.png)

Use tables for comparisons

Tables help users find specific information:

| Plan | Rate Limit | Price |
|------|-----------|-------|
| Free | 100/min | $0 |
| Pro | 1000/min | $99/mo |
| Enterprise | Custom | Custom |

Monitor search performance

Check search analytics

Review search queries in your analytics to:

• Identify common searches
• Find gaps in documentation
• Discover confusing terminology

Test your search

Regularly search for common terms to verify:

• Relevant pages appear in results
• Results are ranked appropriately
• No broken links in results

Update based on feedback

If users report difficulty finding information:

1. Review the page’s title and description
2. Add relevant keywords
3. Improve heading structure
4. Add cross-references

Common search issues

Page not appearing in results

Causes:

• Page not in navigation (hidden pages aren’t indexed)
• Missing or poor title/description
• Recently published (wait 5-10 minutes for indexing)

Solutions:

• Add page to navigation in docs.json
• Improve frontmatter metadata
• Redeploy to trigger reindexing

Wrong pages ranking high

Causes:

• Generic titles across multiple pages
• Keyword stuffing
• Duplicate content

Solutions:

• Make titles more specific
• Use natural language
• Consolidate duplicate content

Search showing outdated content

Causes:

• Search index not updated
• Cached results

Solutions:

• Redeploy your documentation
• Wait 10-15 minutes for index update
• Clear browser cache

Checklist

Use this checklist for each page:

• Descriptive, unique title
• Clear, concise description
• Relevant keywords in frontmatter
• Clear heading structure (H2, H3)
• Important information early in content
• Natural language matching user queries
• Cross-references to related pages
• Code examples with context
• Alt text on images
• Focused on one topic
• Descriptive URL path