From d69b58ab48788d1f99f0862a5156f437cd4587e3 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 24 Jul 2025 18:26:52 -0700 Subject: [PATCH 1/4] create GEO guide --- docs.json | 1 + guides/geo.mdx | 261 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 262 insertions(+) create mode 100644 guides/geo.mdx diff --git a/docs.json b/docs.json index c2e333f1..290f565f 100644 --- a/docs.json +++ b/docs.json @@ -45,6 +45,7 @@ "ai/contextual-menu", "ai/markdown-export", "mcp", + "guides/geo", "guides/claude-code", "guides/cursor", "guides/windsurf" diff --git a/guides/geo.mdx b/guides/geo.mdx new file mode 100644 index 00000000..ad9f3379 --- /dev/null +++ b/guides/geo.mdx @@ -0,0 +1,261 @@ +--- +title: "GEO guide: Optimize docs for AI search and answer engines" +sidebarTitle: "GEO" +description: "Make your documentation more discoverable and cited more frequently by AI tools" +icon: "cpu" +--- + +Optimize your documentation for both traditional search engines and AI-powered answer engines like ChatGPT, Perplexity, and Google AI Overviews. + +Generative Engine Optimization (GEO) focuses on being cited by AI systems through comprehensive content and structured information, while traditional SEO targets search result rankings. + +## GEO best practices + +In general, well written and well structured documentation will have strong GEO. You should still prioritize writing for your users, and if your content is meeting their needs, you will be well on your way to optimizing for AI tools. Creating genuinely helpful content rather than optimizing for optimization's sake is rewarded by both traditional and AI search engines. + +Focus on: + +- Content utility and comprehensive answers +- Structured, scannable information +- Direct answers to questions +- Semantic relevance over keyword matching + +### Create comparison content + +AI engines prioritize content that directly compares options and provides complete information. + +For example, a comparison table: + +```markdown +## API authentication methods + +| Method | Security Level | Implementation | Best For | +|--------|---------------|----------------|----------| +| API Keys | Basic | Simple headers | Internal tools | +| OAuth 2.0 | High | Token exchange | User applications | +| JWT | Medium | Signed tokens | Stateless APIs | +``` + +### Answer questions directly + +Structure documentation to address specific user questions: + +- Begin sections with the main takeaway +- Use descriptive headings that match common queries +- Break complex topics into numbered steps + +## Mintlify configuration + +Use these + +### Enable LLMs.txt generation + +Mintlify automatically generates LLMs.txt files. No additional configuration required. + + +LLMs.txt files help AI systems understand your documentation structure, similar to how sitemaps help search engines. + + +### Optimize page frontmatter + +Add GEO-optimized metadata to each page: + +```mdx +--- +title: 'API Authentication Guide 2025' +description: 'Complete guide to implementing API authentication with code examples' +'og:title': 'API Authentication - Developer Guide' +'og:description': 'Learn how to implement secure API authentication' +--- +``` + +### Configure global SEO settings + +Add to your `docs.json`: + +```json +{ + "seo": { + "indexing": "all", + "metatags": { + "og:type": "website", + "og:site_name": "Your Docs", + "twitter:card": "summary_large_image" + } + } +} +``` + +## Content optimization + +### Structure for AI scanning + +- Use descriptive headings that answer questions +- Lead with direct answers before explanations +- Include numbered steps for procedures +- Add comparison tables for options +- Use bullet points for key information + +### Technical formatting for AI readability + +**Markdown structure requirements:** + +- Use consistent heading hierarchy (don't skip levels) +- Step down one level at a time: H1 → H2 → H3 +- Avoid jumping from H1 directly to H3 + +```markdown +# Main Section +## Subsection +### Specific Topic +#### Implementation Details +``` + +**Writing style guidelines:** + +- Avoid ambiguous pronouns ("it", "this", "that") +- Use specific object names instead +- Maintain consistent terminology throughout documentation + +```markdown +❌ Save it and restart +✅ Save the config.json file and restart the server + +❌ This enables authentication +✅ OAuth 2.0 enables secure authentication +``` + +**Code formatting standards:** + +- Use language-specific code block labels +- Wrap all code in fenced blocks with backticks +- Separate input and output examples clearly + +```markdown +Install the package: +```bash +npm install @mintlify/components +``` + +Example response: +```json +{ + "status": "success", + "data": {} +} +``` + +**Image and media requirements:** + +- Add descriptive alt text to all images +- Include text summaries for visual content +- Ensure content is understandable without viewing media + +```mdx +![API authentication flow diagram showing OAuth 2.0 token exchange between client, authorization server, and resource server](./auth-flow.png) +``` + +### Internal linking strategy + +Connect related concepts to help AI understand relationships: + +```mdx +Learn about [API authentication](/auth/overview) before setting up [OAuth flows](/auth/oauth). + +See also: [Rate limiting](/api/rate-limits) and [Error handling](/api/errors). +``` + +## Writing best practices + +### Documentation standards + +- **Lead with answers** - Start sections with direct solutions +- **Use current examples** - Include 2025 dates and modern tools +- **Add context** - Explain when and why to use features +- **Include troubleshooting** - Address common issues + +### Content structure + +- Clear, descriptive headings +- Numbered steps for procedures +- Bullet points for key features +- Code examples with comments +- Comparison tables for options + + +Use Mintlify components like Warning, Info, and Note to highlight important information that AI systems can better understand and cite. + + +## Testing AI readability + +### Validation methodology + +Test your documentation with AI tools to ensure optimal readability: + +**1. Use ChatGPT or similar AI tools** +- Ask specific workflow questions about your documentation +- Test if AI can find correct sections and extract accurate information +- Verify AI understands step-by-step processes + +**2. Sample test prompts:** +``` +"How do I set up authentication using this API?" +"What are the different pricing tiers and their features?" +"Walk me through the installation process step by step" +``` + +**3. Check for accuracy:** +- AI returns correct code samples +- No context mixing between different topics +- Accurate endpoint and method references +- Clear step-by-step explanations + +**4. Common failure patterns:** +- AI confusing similar but different concepts +- Mixing code examples from different sections +- Inability to follow multi-step procedures +- Misunderstanding due to ambiguous language + +## Measuring GEO performance + +### Key metrics to track + +| Metric Type | Traditional SEO | GEO (AI Search) | +|-------------|----------------|-----------------| +| Traffic | Organic search visits | Direct traffic spikes | +| Visibility | Keyword rankings | AI citation frequency | +| Engagement | Click-through rates | Conversion from AI referrals | + +### Analytics setup + + +AI search traffic often appears as direct traffic. Monitor traffic patterns and add AI search sources to your attribution models. + + +Track these sources in your analytics: +- Direct traffic (often from AI) +- Brand searches (post-AI citation) +- Referrals from AI platforms when available + +## Quick start checklist + +### Initial setup + +1. **Configure Mintlify SEO settings** in `docs.json` +2. **Audit current pages** for missing descriptions and titles +3. **Add structured frontmatter** to key pages +4. **Enable LLMs.txt generation** (automatic in Mintlify) + +### Content optimization + +1. **Rewrite page titles** to include current year and answer questions +2. **Add comparison tables** for feature documentation +3. **Create FAQ sections** for common user questions +4. **Improve internal linking** between related topics + +### Ongoing maintenance + +- Update time-sensitive content annually +- Monitor traffic patterns for AI referrals +- Add new comparison content quarterly +- Review and update FAQ sections monthly From c83397948e7d3585bb5e86f0e19d6ee7e4680c84 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 24 Jul 2025 18:42:07 -0700 Subject: [PATCH 2/4] copyedit --- guides/geo.mdx | 236 ++++++++++++------------------------------------- 1 file changed, 57 insertions(+), 179 deletions(-) diff --git a/guides/geo.mdx b/guides/geo.mdx index ad9f3379..e3dd8303 100644 --- a/guides/geo.mdx +++ b/guides/geo.mdx @@ -9,6 +9,20 @@ Optimize your documentation for both traditional search engines and AI-powered a Generative Engine Optimization (GEO) focuses on being cited by AI systems through comprehensive content and structured information, while traditional SEO targets search result rankings. +## GEO quickstart + +### Initial setup + +1. **Configure SEO settings** in `docs.json` +2. **Audit current pages** for missing descriptions and titles + +### Content improvements + +1. **Add comparison tables** to appropriate pages +2. **Audit headings** to ensure they answer common questions +3. **Improve internal linking** between related topics +4. **Test with AI tools** to verify accuracy + ## GEO best practices In general, well written and well structured documentation will have strong GEO. You should still prioritize writing for your users, and if your content is meeting their needs, you will be well on your way to optimizing for AI tools. Creating genuinely helpful content rather than optimizing for optimization's sake is rewarded by both traditional and AI search engines. @@ -44,218 +58,82 @@ Structure documentation to address specific user questions: - Use descriptive headings that match common queries - Break complex topics into numbered steps -## Mintlify configuration - -Use these - -### Enable LLMs.txt generation - -Mintlify automatically generates LLMs.txt files. No additional configuration required. - - -LLMs.txt files help AI systems understand your documentation structure, similar to how sitemaps help search engines. - - -### Optimize page frontmatter - -Add GEO-optimized metadata to each page: - -```mdx ---- -title: 'API Authentication Guide 2025' -description: 'Complete guide to implementing API authentication with code examples' -'og:title': 'API Authentication - Developer Guide' -'og:description': 'Learn how to implement secure API authentication' ---- -``` - -### Configure global SEO settings - -Add to your `docs.json`: - -```json -{ - "seo": { - "indexing": "all", - "metatags": { - "og:type": "website", - "og:site_name": "Your Docs", - "twitter:card": "summary_large_image" - } - } -} -``` - -## Content optimization - -### Structure for AI scanning +### Content structure - Use descriptive headings that answer questions -- Lead with direct answers before explanations +- Begin with the main takeaway - Include numbered steps for procedures - Add comparison tables for options -- Use bullet points for key information - -### Technical formatting for AI readability -**Markdown structure requirements:** +### Format for clarity -- Use consistent heading hierarchy (don't skip levels) -- Step down one level at a time: H1 → H2 → H3 -- Avoid jumping from H1 directly to H3 - -```markdown -# Main Section -## Subsection -### Specific Topic -#### Implementation Details -``` - -**Writing style guidelines:** - -- Avoid ambiguous pronouns ("it", "this", "that") -- Use specific object names instead -- Maintain consistent terminology throughout documentation +**Keep heading hierarchy consistent:** +- Don't skip heading levels (H1 → H2 → H3) +- Use specific object names instead of "it" or "this" +- Label code blocks with the programming language ```markdown ❌ Save it and restart ✅ Save the config.json file and restart the server - -❌ This enables authentication -✅ OAuth 2.0 enables secure authentication ``` -**Code formatting standards:** +**Code examples:** -- Use language-specific code block labels -- Wrap all code in fenced blocks with backticks -- Separate input and output examples clearly -```markdown -Install the package: -```bash -npm install @mintlify/components -``` +**Images need descriptive alt text: -Example response: -```json -{ - "status": "success", - "data": {} -} -``` - -**Image and media requirements:** - -- Add descriptive alt text to all images -- Include text summaries for visual content -- Ensure content is understandable without viewing media - -```mdx -![API authentication flow diagram showing OAuth 2.0 token exchange between client, authorization server, and resource server](./auth-flow.png) -``` -### Internal linking strategy +### Connect related topics -Connect related concepts to help AI understand relationships: +Link to related concepts to help AI understand relationships: ```mdx Learn about [API authentication](/auth/overview) before setting up [OAuth flows](/auth/oauth). - -See also: [Rate limiting](/api/rate-limits) and [Error handling](/api/errors). ``` -## Writing best practices - -### Documentation standards - -- **Lead with answers** - Start sections with direct solutions -- **Use current examples** - Include 2025 dates and modern tools -- **Add context** - Explain when and why to use features -- **Include troubleshooting** - Address common issues - -### Content structure - -- Clear, descriptive headings -- Numbered steps for procedures -- Bullet points for key features -- Code examples with comments -- Comparison tables for options - - -Use Mintlify components like Warning, Info, and Note to highlight important information that AI systems can better understand and cite. - - -## Testing AI readability +## Mintlify configuration -### Validation methodology +Use these features to improve GEO. -Test your documentation with AI tools to ensure optimal readability: +### Add descriptive page metadata -**1. Use ChatGPT or similar AI tools** -- Ask specific workflow questions about your documentation -- Test if AI can find correct sections and extract accurate information -- Verify AI understands step-by-step processes +Include clear titles and descriptions in your frontmatter: -**2. Sample test prompts:** -``` -"How do I set up authentication using this API?" -"What are the different pricing tiers and their features?" -"Walk me through the installation process step by step" +```mdx +--- +title: "API authentication guide" +description: "Complete guide to implementing API authentication with code examples" +--- ``` -**3. Check for accuracy:** -- AI returns correct code samples -- No context mixing between different topics -- Accurate endpoint and method references -- Clear step-by-step explanations - -**4. Common failure patterns:** -- AI confusing similar but different concepts -- Mixing code examples from different sections -- Inability to follow multi-step procedures -- Misunderstanding due to ambiguous language - -## Measuring GEO performance - -### Key metrics to track - -| Metric Type | Traditional SEO | GEO (AI Search) | -|-------------|----------------|-----------------| -| Traffic | Organic search visits | Direct traffic spikes | -| Visibility | Keyword rankings | AI citation frequency | -| Engagement | Click-through rates | Conversion from AI referrals | - -### Analytics setup - - -AI search traffic often appears as direct traffic. Monitor traffic patterns and add AI search sources to your attribution models. - +### Configure global SEO settings -Track these sources in your analytics: -- Direct traffic (often from AI) -- Brand searches (post-AI citation) -- Referrals from AI platforms when available +Add to your `docs.json`: -## Quick start checklist +```json +{ + "seo": { + "indexing": "all", + "metatags": { + "og:type": "website", + "og:site_name": "Your docs" + } + } +} +``` -### Initial setup +### LLMs.txt -1. **Configure Mintlify SEO settings** in `docs.json` -2. **Audit current pages** for missing descriptions and titles -3. **Add structured frontmatter** to key pages -4. **Enable LLMs.txt generation** (automatic in Mintlify) +LLMs.txt files help AI systems understand your documentation structure, similar to how sitemaps help search engines. Mintlify automatically generates LLMs.txt files for your docs. No configuration is required. -### Content optimization +## Testing your documentation -1. **Rewrite page titles** to include current year and answer questions -2. **Add comparison tables** for feature documentation -3. **Create FAQ sections** for common user questions -4. **Improve internal linking** between related topics +Test various AI tools with questions about your product and documentation to see how well your docs are being cited. -### Ongoing maintenance +**Ask AI assistants specific questions about your docs:** +- "How do I set up authentication using this API?" +- "Walk me through the installation process step by step" -- Update time-sensitive content annually -- Monitor traffic patterns for AI referrals -- Add new comparison content quarterly -- Review and update FAQ sections monthly +**Check that tools provide:** +- Correct code samples +- Accurate step-by-step instructions From 57f577ccc112c0495d81980c4b426088cedec88a Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Thu, 24 Jul 2025 18:47:59 -0700 Subject: [PATCH 3/4] remove redundancy --- guides/geo.mdx | 35 ++++++----------------------------- 1 file changed, 6 insertions(+), 29 deletions(-) diff --git a/guides/geo.mdx b/guides/geo.mdx index e3dd8303..37099464 100644 --- a/guides/geo.mdx +++ b/guides/geo.mdx @@ -52,44 +52,21 @@ For example, a comparison table: ### Answer questions directly -Structure documentation to address specific user questions: +Write content that addresses specific user questions: - Begin sections with the main takeaway - Use descriptive headings that match common queries - Break complex topics into numbered steps -### Content structure - -- Use descriptive headings that answer questions -- Begin with the main takeaway -- Include numbered steps for procedures -- Add comparison tables for options - ### Format for clarity -**Keep heading hierarchy consistent:** +These formatting practices help AI tools parse and understand your content: + - Don't skip heading levels (H1 → H2 → H3) - Use specific object names instead of "it" or "this" -- Label code blocks with the programming language - -```markdown -❌ Save it and restart -✅ Save the config.json file and restart the server -``` - -**Code examples:** - - -**Images need descriptive alt text: - - -### Connect related topics - -Link to related concepts to help AI understand relationships: - -```mdx -Learn about [API authentication](/auth/overview) before setting up [OAuth flows](/auth/oauth). -``` +- Label code blocks with their programming language +- Give images descriptive alt text +- Link to related concepts to help AI understand relationships ## Mintlify configuration From 8ed6f7d1a0d8bd07e04ba023b8f2bc351bcd56c8 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 25 Jul 2025 11:16:44 -0700 Subject: [PATCH 4/4] add reviewer feedback --- guides/geo.mdx | 37 ++++++++++--------------------------- 1 file changed, 10 insertions(+), 27 deletions(-) diff --git a/guides/geo.mdx b/guides/geo.mdx index 37099464..d4294ad1 100644 --- a/guides/geo.mdx +++ b/guides/geo.mdx @@ -13,7 +13,7 @@ Generative Engine Optimization (GEO) focuses on being cited by AI systems throug ### Initial setup -1. **Configure SEO settings** in `docs.json` +1. **Make sure your docs are being indexed** in your `docs.json` settings 2. **Audit current pages** for missing descriptions and titles ### Content improvements @@ -29,26 +29,19 @@ In general, well written and well structured documentation will have strong GEO. Focus on: -- Content utility and comprehensive answers +- Content aligned to user needs rather than keyword matching - Structured, scannable information - Direct answers to questions -- Semantic relevance over keyword matching -### Create comparison content - -AI engines prioritize content that directly compares options and provides complete information. - -For example, a comparison table: +### Format for clarity -```markdown -## API authentication methods +These formatting practices help AI tools parse and understand your content: -| Method | Security Level | Implementation | Best For | -|--------|---------------|----------------|----------| -| API Keys | Basic | Simple headers | Internal tools | -| OAuth 2.0 | High | Token exchange | User applications | -| JWT | Medium | Signed tokens | Stateless APIs | -``` +- Don't skip heading levels (H1 → H2 → H3) +- Use specific object names instead of "it" or "this" +- Label code blocks with their programming language +- Give images descriptive alt text +- Link to related concepts to help AI understand relationships ### Answer questions directly @@ -58,16 +51,6 @@ Write content that addresses specific user questions: - Use descriptive headings that match common queries - Break complex topics into numbered steps -### Format for clarity - -These formatting practices help AI tools parse and understand your content: - -- Don't skip heading levels (H1 → H2 → H3) -- Use specific object names instead of "it" or "this" -- Label code blocks with their programming language -- Give images descriptive alt text -- Link to related concepts to help AI understand relationships - ## Mintlify configuration Use these features to improve GEO. @@ -83,7 +66,7 @@ description: "Complete guide to implementing API authentication with code exampl --- ``` -### Configure global SEO settings +### Configure global indexing settings Add to your `docs.json`: