This page explains fundamental strategies to optimize your documentation SEO.
Content basics
Make your writing and structure easy for search engines to scan.
Heading hierarchy
Use sequential, meaningful headers to structure your content. Each page has an H1 created from the title: property in the frontmatter. Follow these best practices:
- Use only one H1 per page (automatically generated from frontmatter)
- Follow a logical hierarchy: H1 → H2 → H3 (don’t skip levels)
- Include relevant keywords in headings naturally
- Keep headings descriptive and concise (under 70 characters)
- Use sentence case for consistency
Content structure
Break down large chunks of text into easily readable sections:
- Short paragraphs: Aim for 2-4 sentences per paragraph
- Bullet points and lists: Use for scannable information
- Code examples: Include practical, working examples
- Visual aids: Add diagrams, screenshots, or videos where helpful
- Tables: Organize comparative or structured data
Internal linking strategy
Link to related content using descriptive anchor text:
- Use descriptive anchor text: “Learn more about rate limiting” instead of “Click here”
- Link to related pages within your documentation to create topic clusters
- Add contextual links within body content, not just at the end
- Ensure all important pages are linked from at least one other page
- Use relative paths for internal links to maintain portability
Technical SEO basics
Once your content is optimized, ensure your documentation performs well from a technical standpoint.
Craft SEO-friendly titles and descriptions for each page. Most meta tags are automatically generated, but you can customize them:
- Title tags: Keep between 50-60 characters to avoid truncation in search results
- Meta descriptions: Write compelling descriptions between 150-160 characters
- Include target keywords: Place primary keywords near the beginning
- Make each unique: Every page should have a distinct title and description
- Match user intent: Describe what users will learn or accomplish
Example frontmatter:
---
title: "API authentication guide"
description: "Learn how to authenticate API requests using OAuth 2.0, API keys, and JWT tokens with code examples."
keywords: ["API authentication", "OAuth 2.0", "JWT", "API keys"]
---
Image optimization
Provide descriptive alt text for images with relevant keywords:
- Use descriptive file names:
oauth-flow-diagram.png instead of image1.png
- Write meaningful alt text: “OAuth 2.0 API authentication flow diagram” instead of “diagram”
- Keep alt text under 125 characters
- Don’t start with “image of” or “picture of”
- Include keywords naturally without stuffing
- Compress images to reduce file size (use WebP or AVIF formats)
Sitemaps and indexing
Mintlify automatically generates a sitemap at /sitemap.xml:
- Sitemaps are automatically updated when you deploy
- Submit your sitemap to Google Search Console to speed up indexing
- Use the
seo.indexing field in docs.json to control which pages are included
- Monitor indexing status and fix any crawl errors in Search Console
URL structure
Create clean, descriptive URLs:
- Use lowercase letters and hyphens (not underscores)
- Keep URLs short and descriptive:
/api/authentication not /api/auth-guide-v2-final
- Follow a logical hierarchy that matches your navigation
- Avoid special characters, spaces, or unnecessary parameters
- Use consistent patterns across your documentation
Page performance
Page speed is a critical ranking factor. Use tools like Google PageSpeed Insights and WebPageTest to identify areas for improvement.
Core Web Vitals
Focus on these key metrics that Google uses for ranking:
- Largest Contentful Paint (LCP): Should occur within 2.5 seconds
- First Input Delay (FID): Should be less than 100 milliseconds
- Cumulative Layout Shift (CLS): Should be less than 0.1
- Optimize media: Compress images using WebP or AVIF formats
- Lazy load images: Load images only when they enter the viewport
- Minimize JavaScript: Remove unused code and defer non-critical scripts
- Enable caching: Leverage browser caching for static assets
- Use a CDN: Serve content from geographically distributed servers
- Target load time: Aim for pages to load in under 3 seconds
Structured data (schema markup)
Add schema markup to help search engines better understand and rank your content:
- HowTo schema: For step-by-step guides and tutorials
- FAQ schema: For frequently asked questions
- Article schema: For blog posts and documentation articles
- BreadcrumbList schema: For navigation breadcrumbs
- SoftwareApplication schema: For API and SDK documentation
Test your structured data using Google’s Rich Results Test.
Mobile optimization
Ensure your documentation works well on mobile devices:
- Use responsive design that adapts to different screen sizes
- Ensure text is readable without zooming (minimum 16px font size)
- Make tap targets at least 48x48 pixels
- Avoid horizontal scrolling
- Test on real devices, not just emulators
Keyword research
To increase organic traffic, invest time into understanding which keywords help users land on your documentation.
Finding the right keywords
Use these tools to identify valuable keywords:
Keyword strategy
Focus on these types of keywords:
- Primary keywords: Main topics your documentation covers (e.g., “REST API authentication”)
- Long-tail keywords: Specific phrases with lower competition (e.g., “how to implement OAuth 2.0 in Node.js”)
- Question keywords: Queries starting with who, what, where, when, why, how
- Intent-based keywords: Match what users are trying to accomplish (e.g., “troubleshoot API errors”)
Keyword implementation
Add keywords naturally throughout your content:
- Title and H1: Include primary keyword near the beginning
- First paragraph: Use primary keyword within the first 100 words
- Headings (H2, H3): Include related keywords and variations
- Body text: Use keywords naturally throughout, including synonyms
- Image alt text: Include relevant keywords in image descriptions
- URL slug: Use primary keyword in the page URL
Important: Don’t overstuff keywords. Your documentation should be written for your users, not search engines. Aim for natural language that provides value.
Monitoring and analytics
Track your SEO performance to understand what’s working:
Key metrics to monitor
- Organic traffic: Total visits from search engines
- Keyword rankings: Position in search results for target keywords
- Click-through rate (CTR): Percentage of users who click your result
- Bounce rate: Percentage of users who leave after viewing one page
- Time on page: How long users spend reading your content
- Pages per session: How many pages users visit
- Google Search Console: Monitor search performance, indexing, and issues
- Google Analytics: Track traffic, user behavior, and conversions
- Ahrefs or SEMrush: Monitor rankings and backlinks
- Mintlify Insights: Built-in analytics for documentation engagement
Continuous improvement
- Review analytics monthly to identify trends
- Update underperforming pages with better content
- Refresh outdated content to maintain rankings
- Add new content targeting high-value keywords
- Fix technical issues promptly (broken links, slow pages, crawl errors)
