From c85903712258ac986e547e4b53c779530eaba74f Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 21 Nov 2025 20:58:28 +0000 Subject: [PATCH 1/9] Update guides/seo.mdx --- guides/seo.mdx | 32 +++++++++++++++++++++++++++++--- 1 file changed, 29 insertions(+), 3 deletions(-) diff --git a/guides/seo.mdx b/guides/seo.mdx index 888a231c8..efdcf96ad 100644 --- a/guides/seo.mdx +++ b/guides/seo.mdx @@ -12,9 +12,35 @@ This page explains fundamental strategies to optimize your documentation SEO. 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 From 8a56b2dc38583f94cda3dd20e95210cb0df27f93 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 21 Nov 2025 20:58:48 +0000 Subject: [PATCH 2/9] Update guides/seo.mdx --- guides/seo.mdx | 53 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 48 insertions(+), 5 deletions(-) diff --git a/guides/seo.mdx b/guides/seo.mdx index efdcf96ad..f299e64ff 100644 --- a/guides/seo.mdx +++ b/guides/seo.mdx @@ -44,13 +44,56 @@ Link to related content using descriptive anchor text: ## 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. -These basic technical SEO practices help make your docs more discoverable: +### Meta tags and descriptions -- **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. +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 + +Mintlify automatically generates a sitemap at `/sitemap.xml`: + +- 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 From ae845a5657707dcc088aaf4bee6874c9f93cf2e3 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 21 Nov 2025 20:59:03 +0000 Subject: [PATCH 3/9] Update guides/seo.mdx --- guides/seo.mdx | 42 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 38 insertions(+), 4 deletions(-) diff --git a/guides/seo.mdx b/guides/seo.mdx index f299e64ff..73a51fb7b 100644 --- a/guides/seo.mdx +++ b/guides/seo.mdx @@ -97,12 +97,46 @@ Create clean, descriptive URLs: ## 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. -Examples of more advanced optimizations: +### Core Web Vitals -- **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. +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 + +### Performance optimization + +- **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 From 7cf1c4b4737d8a55f2164ce708b5e659ce803209 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 21 Nov 2025 20:59:24 +0000 Subject: [PATCH 4/9] Update guides/seo.mdx --- guides/seo.mdx | 61 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 59 insertions(+), 2 deletions(-) diff --git a/guides/seo.mdx b/guides/seo.mdx index 73a51fb7b..ddf8a21b9 100644 --- a/guides/seo.mdx +++ b/guides/seo.mdx @@ -142,5 +142,62 @@ Ensure your documentation works well on mobile devices: 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) From 81cd6a117b74d45ee76d40e2d56366f59efb8316 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 21 Nov 2025 20:59:37 +0000 Subject: [PATCH 5/9] Update optimize/seo.mdx --- optimize/seo.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/optimize/seo.mdx b/optimize/seo.mdx index c310e3c97..52c48609b 100644 --- a/optimize/seo.mdx +++ b/optimize/seo.mdx @@ -6,10 +6,12 @@ keywords: ["meta tags", "sitemap", "robots.txt", "SEO", "search engine optimizat Mintlify automatically handles many SEO best practices, including: -- Meta tag generation -- Sitemap and `robots.txt` file generation -- Semantic HTML structure -- Mobile optimization +- **Meta tag generation:** Automatic creation of essential meta tags from page frontmatter +- **Sitemap and `robots.txt` file generation:** Automatic generation and updates on deployment +- **Semantic HTML structure:** Proper heading hierarchy and semantic elements +- **Mobile optimization:** Responsive design that works across all devices +- **Fast page loads:** Optimized assets and efficient rendering +- **Clean URLs:** SEO-friendly URL structure based on file paths You can fully customize your site's meta tags by adding the `metatags` field to your `docs.json` or a page's frontmatter. From a923fe57accec69992f648e79d68e79a5fb914fd Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 21 Nov 2025 20:59:48 +0000 Subject: [PATCH 6/9] Update optimize/seo.mdx --- optimize/seo.mdx | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/optimize/seo.mdx b/optimize/seo.mdx index 52c48609b..bc54da094 100644 --- a/optimize/seo.mdx +++ b/optimize/seo.mdx @@ -29,7 +29,13 @@ To set default meta tags for all pages, add the `metatags` field to your `docs.j ### Set a canonical URL -If you're using a custom domain, set the `canonical` meta tag to ensure search engines index your preferred domain. A canonical URL tells search engines which version of your documentation is the primary one. This improves SEO when your documentation is accessible from multiple URLs and prevents issues with duplicate content. +If you're using a custom domain, set the `canonical` meta tag to ensure search engines index your preferred domain. A canonical URL tells search engines which version of your documentation is the primary one. + +**Why canonical URLs matter:** +- Prevents duplicate content issues when docs are accessible from multiple URLs +- Consolidates ranking signals to your preferred domain +- Helps search engines understand which version to index +- Essential when using custom domains, subdomains, or CDN URLs ```json "seo": { @@ -39,6 +45,10 @@ If you're using a custom domain, set the `canonical` meta tag to ensure search e } ``` + +The canonical URL should be the primary domain where you want search traffic directed. Don't include the page path—Mintlify automatically appends it. + + ## Page-specific meta tags To set page-specific meta tags, add them to a page's frontmatter. From 7f5007160e41c4525548cb3d7677b04257603eb7 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 21 Nov 2025 21:00:03 +0000 Subject: [PATCH 7/9] Update optimize/seo.mdx --- optimize/seo.mdx | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/optimize/seo.mdx b/optimize/seo.mdx index bc54da094..37761c86e 100644 --- a/optimize/seo.mdx +++ b/optimize/seo.mdx @@ -171,7 +171,9 @@ You can preview how your meta tags will appear on different platforms using [met Mintlify automatically generates a `sitemap.xml` file and a `robots.txt` file. You can view your sitemap by appending `/sitemap.xml` to your documentation site's URL. -Only pages included in your `docs.json` are included by default. To include hidden links, add `seo.indexing` to your `docs.json`: +### Sitemap configuration + +Only pages included in your `docs.json` navigation are included by default. To include hidden pages, add `seo.indexing` to your `docs.json`: ```json "seo": { @@ -179,10 +181,32 @@ Only pages included in your `docs.json` are included by default. To include hidd } ``` +**Indexing options:** +- `"navigable"` (default): Only pages in your navigation structure +- `"all"`: All pages, including hidden pages and those not in navigation + +### Submitting your sitemap + +After deploying your documentation: + +1. Visit [Google Search Console](https://search.google.com/search-console) +2. Add and verify your property (domain or URL prefix) +3. Navigate to "Sitemaps" in the left sidebar +4. Enter your sitemap URL: `https://yourdomain.com/sitemap.xml` +5. Click "Submit" + +Google will begin crawling and indexing your pages. This process can take a few days to several weeks. + ### Custom sitemaps and robots.txt files To add a custom `sitemap.xml` or `robots.txt` file, create a `sitemap.xml` or `robots.txt` file at the root of your project. Adding a custom file will override the automatically generated file of the same name. If you delete a custom file, the default file will be used again. +**When to use custom files:** +- You need specific sitemap formatting for third-party tools +- You want to exclude specific user agents in robots.txt +- You need multiple sitemaps for different content types +- You want to add custom crawl delays or directives + ## Disabling indexing If you want to stop a page from being indexed by search engines, you can include the following in the [frontmatter](/organize/pages) of your page: From 980b8072ae89bcdd5217b8d936916398d578698f Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 21 Nov 2025 21:00:19 +0000 Subject: [PATCH 8/9] Update optimize/seo.mdx --- optimize/seo.mdx | 43 ++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 40 insertions(+), 3 deletions(-) diff --git a/optimize/seo.mdx b/optimize/seo.mdx index 37761c86e..e7a7ad6c7 100644 --- a/optimize/seo.mdx +++ b/optimize/seo.mdx @@ -209,15 +209,28 @@ To add a custom `sitemap.xml` or `robots.txt` file, create a `sitemap.xml` or `r ## Disabling indexing -If you want to stop a page from being indexed by search engines, you can include the following in the [frontmatter](/organize/pages) of your page: +Control which pages search engines can index using the `noindex` directive. -``` +### Per-page noindex + +To prevent a specific page from being indexed, add `noindex` to the page's [frontmatter](/organize/pages): + +```yaml --- +title: "Internal documentation" noindex: true --- ``` -You can also specify `noindex` for all pages in your docs by setting the `metatags.robots` field to `"noindex"` in your `docs.json`: +**Common use cases:** +- Internal or draft documentation +- Deprecated pages that should remain accessible but not searchable +- Staging or preview environments +- Pages with duplicate content + +### Site-wide noindex + +To prevent all pages from being indexed, set the `metatags.robots` field in your `docs.json`: ```json "seo": { @@ -227,6 +240,30 @@ You can also specify `noindex` for all pages in your docs by setting the `metata } ``` + +Use site-wide `noindex` carefully. This prevents all pages from appearing in search results, which is typically only appropriate for staging environments or internal documentation. + + +### Other robots directives + +You can use additional robots meta tag directives: + +```json +"seo": { + "metatags": { + "robots": "noindex, nofollow", // Don't index and don't follow links + "googlebot": "noindex" // Specific to Google's crawler + } + } +``` + +**Available directives:** +- `index` / `noindex`: Allow or prevent indexing +- `follow` / `nofollow`: Allow or prevent following links +- `noarchive`: Prevent cached copies in search results +- `nosnippet`: Prevent text snippets in search results +- `noimageindex`: Prevent images from being indexed + ## SEO best practices From 6fee83a2ce627498379e90e9e648cb6d2dfbb8cf Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 21 Nov 2025 21:00:47 +0000 Subject: [PATCH 9/9] Update optimize/seo.mdx --- optimize/seo.mdx | 104 +++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 101 insertions(+), 3 deletions(-) diff --git a/optimize/seo.mdx b/optimize/seo.mdx index e7a7ad6c7..b9385214c 100644 --- a/optimize/seo.mdx +++ b/optimize/seo.mdx @@ -270,8 +270,11 @@ You can use additional robots meta tag directives: - Use clear, descriptive page titles (50-60 characters) - Write compelling descriptions (150-160 characters) -- Include relevant keywords +- Include relevant keywords naturally - Make each page title and description unique +- Place primary keywords near the beginning +- Match user search intent +- Avoid keyword stuffing or clickbait @@ -280,19 +283,114 @@ You can use additional robots meta tag directives: - Include relevant keywords in headings and content - Keep URLs short, descriptive, and organized hierarchically - Break up long content with subheadings and lists +- Use bullet points for scannable information +- Add code examples and practical demonstrations +- Include visual aids (diagrams, screenshots, videos) - Link to related pages within your documentation - Use descriptive anchor text instead of "click here" - Create topic clusters by linking related concepts -- Use the automatic cross-referencing features +- Ensure all important pages are linked from at least one other page +- Add contextual links within body content +- Use relative paths for internal links +- Fix broken links promptly -- Use descriptive file names for images +- Use descriptive file names: `oauth-flow-diagram.png` not `image1.png` - Always include alt text for accessibility and SEO +- Keep alt text under 125 characters - Optimize image file sizes for faster loading +- Use modern formats (WebP, AVIF) when possible +- Implement lazy loading for images below the fold - Use relevant images that support your content +- Compress images without sacrificing quality + + + +- Ensure fast page load times (under 3 seconds) +- Optimize Core Web Vitals (LCP, FID, CLS) +- Use semantic HTML elements +- Implement structured data (schema markup) +- Ensure mobile responsiveness +- Enable HTTPS for security +- Minimize JavaScript and CSS +- Use a CDN for faster content delivery + + + +- Update outdated content regularly +- Add publication and update dates where relevant +- Refresh underperforming pages +- Remove or redirect obsolete pages +- Monitor for broken links and fix them +- Keep code examples current with latest versions +- Add new content targeting high-value keywords + +## Advanced SEO techniques + +### Schema markup + +Add structured data to help search engines understand your content: + +```html + +``` + +### Open Graph tags + +Optimize social media sharing with Open Graph tags: + +```json +"seo": { + "metatags": { + "og:title": "API Authentication Guide", + "og:description": "Learn how to authenticate API requests using OAuth 2.0", + "og:image": "https://yourdomain.com/images/auth-guide.png", + "og:type": "article", + "twitter:card": "summary_large_image" + } +} +``` + +### International SEO + +For multi-language documentation, use hreflang tags: + +```json +"seo": { + "metatags": { + "hreflang": "en-us" + } +} +``` + +Configure language alternatives in your navigation structure using the [languages](/organize/navigation#languages) feature. + +### Backlink strategy + +Build authority through quality backlinks: + +- Create valuable, shareable content +- Contribute to developer communities (Stack Overflow, Reddit, Dev.to) +- Write guest posts on relevant blogs +- Get listed in developer resource directories +- Engage with your community on social media +- Create tools or resources others want to link to