Enhanced SEO documentation with comprehensive details

guides/seo.mdx

@@ -1,43 +1,203 @@
 ---
 title: "SEO"
 description: "Improve SEO to increase documentation discoverability."
 keywords: ["search engine optimization", "meta tags", "keyword research"]
 ---
 
 <Tip>
 This page explains fundamental strategies to optimize your documentation SEO.
 </Tip>
 
 ## Content basics
 
 Make your writing and structure easy for search engines to scan.
 
-- **Headings and subheadings:** Use sequential, meaningful headers to structure your content. Each page has an H1 created from the `title:` property in the frontmatter.
-- **Short paragraphs and bullet points:** Break down large chunks of text into easily readable sections. Use bullet points and numbered lists where appropriate.
-- **Internal linking:** Link to related content using descriptive anchor text. For example, "Learn more about rate limiting" instead of "Click here."
+### 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](/api/rate-limits)" 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. 
+Once your content is optimized, ensure your documentation performs well from a technical standpoint.
+
+### Meta tags and descriptions
+
+Craft SEO-friendly titles and descriptions for each page. Most [meta tags](/optimize/seo) 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:
+```yaml
+---
+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
 
-These basic technical SEO practices help make your docs more discoverable:
+Mintlify automatically generates a sitemap at `/sitemap.xml`:
 
-- **Meta tags and descriptions:** Craft SEO-friendly titles (50-60 characters) and descriptions (150-160 characters) for each page. Most [meta tags](/optimize/seo) are automatically generated.
-- **Alt text for images:** Provide descriptive alt text for images with relevant keywords. For example, "OAuth 2.0 API authentication flow" instead of just "diagram". This enhances SEO and accessibility.
-- **Sitemaps:** Ensure your sitemap is up-to-date. Mintlify automatically generates a sitemap. However, you can manually create a sitemap if you prefer a custom format. Once created, search engines index site maps over time, but you can submit your sitemap directly to Google Search Console to speed up the process.
+- Sitemaps are automatically updated when you deploy
+- Submit your sitemap to [Google Search Console](https://search.google.com/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
 
-Use tools like [Google PageSpeed Insights](https://pagespeed.web.dev) to identify areas for technical SEO improvement.
+Page speed is a critical ranking factor. Use tools like [Google PageSpeed Insights](https://pagespeed.web.dev) and [WebPageTest](https://www.webpagetest.org) 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
 
-Examples of more advanced optimizations: 
+### Performance optimization
 
-- **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.
+- **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](https://search.google.com/test/rich-results).
+
+### 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.
 
-- **Keyword research:** Use free tools like [Google Keyword Planner](https://ads.google.com/intl/en_us/home/tools/keyword-planner/) or [Keywords Everywhere](https://keywordseverywhere.com) to identify common phrases or long-tail keywords.
-- **Integrate keywords naturally:** Add keywords naturally into headings, subheadings, and throughout the body text. Don't overstuff keywords. Your documentation should be written for your users, not search engines.
+### Finding the right keywords
+
+Use these tools to identify valuable keywords:
+
+- **[Google Keyword Planner](https://ads.google.com/intl/en_us/home/tools/keyword-planner/):** Free tool for search volume and competition data
+- **[Google Search Console](https://search.google.com/search-console):** See which queries already drive traffic to your docs
+- **[Ahrefs](https://ahrefs.com) or [SEMrush](https://www.semrush.com):** Comprehensive keyword research and competitor analysis
+- **[AnswerThePublic](https://answerthepublic.com):** Discover questions people ask about your topics
+- **[Keywords Everywhere](https://keywordseverywhere.com):** Browser extension for keyword data
+
+### 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
+
+### Tools for monitoring
+
+- **[Google Search Console](https://search.google.com/search-console):** Monitor search performance, indexing, and issues
+- **[Google Analytics](https://analytics.google.com):** Track traffic, user behavior, and conversions
+- **[Ahrefs](https://ahrefs.com) or [SEMrush](https://www.semrush.com):** 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)