This page explains fundamental strategies to optimize your documentation SEO.
Content fundamentals
Structure content for search engines and readers:
- Headings and subheadings: Use sequential, meaningful headers. Each page has an H1 from the
title: property in frontmatter.
- Short paragraphs and lists: Break large text blocks into readable sections. Use bullet points and numbered lists.
- Internal linking: Link to related content with descriptive anchor text. Write “Learn more about rate limiting” instead of “Click here.”
Technical SEO essentials
Optimize technical elements for better discoverability:
- Meta tags and descriptions: Write SEO-friendly titles (50-60 characters) and descriptions (150-160 characters). Most meta tags are automatically generated.
- Alt text for images: Include descriptive alt text with relevant keywords. Write “OAuth 2.0 API authentication flow” instead of “diagram” to improve SEO and accessibility.
- Sitemaps: Mintlify automatically generates sitemaps. Submit your sitemap to Google Search Console to accelerate indexing.
Page performance
Use tools like Google PageSpeed Insights to identify areas for technical SEO improvement.
Examples of more advanced optimizations:
- Optimize media for speed: Compress images using formats like WebP or AVIF and ensure your pages load quickly (ideally under 3 seconds).
- Structured data (schema markup): Add schema markup (like HowTo, FAQ) to your pages to help search engines better understand and rank your content.
Keyword research
Understand which keywords drive users to your documentation:
- Research keywords: Use tools like Google Keyword Planner or Keywords Everywhere to identify common phrases and long-tail keywords.
- Integrate naturally: Add keywords to headings, subheadings, and body text where they fit naturally. Avoid keyword stuffing. Write for users, not search engines.
