docs-seo — SEO Analysis for Documentation

Workflow#

1. Check the platform's SEO switches first — before auditing content, find out whether the publishing platform generates structured data (JSON-LD) and whether it is turned on. This is the single highest-leverage finding: perfect content markup is worthless if the platform ships it behind a disabled toggle. On Docsbook, read the workspace's seo / geo / aeo flags via get_info (MCP) or the SEO / GEO panel in the dashboard. See Platform SEO switches below for what each flag emits and why a disabled aeo/geo is often the biggest AI-citability gap. If the platform has no such switches, skip this step — the audit is then purely your markdown frontmatter.
2. Gather the docs — get the list of pages in scope (with titles and frontmatter) and read their content. If a semantic/graph search tool over the markdown is available (self-hosted markdown-lsp, or a connected Docsbook workspace), prefer it — faster and cheaper than scanning files; otherwise read the files directly with grep/find. Prioritize Tier 1 pages (quick-start, pricing, auth, install) first. Skip if docs are private or internal.
3. Apply checklist — check titles, descriptions, heading structure, body content, images, internal links (topic clusters), URL/file path conventions, and AI Overviews / GEO criteria.
4. Produce report — return one JSON issue object per finding, sorted by severity. Cross-page checks (duplicate titles, orphan pages) require the full graph. Lead the report with any disabled platform SEO switch found in step 1.

Guardrails#

• Do not run on private or internal documentation — SEO only applies to public docs.
• Do not edit any documentation files — surface findings only.
• Cross-page checks (duplicate titles, orphan pages) can only be found by scanning all pages together — run these after reading individual pages.
• Ask the user to confirm primary keywords per page before flagging title/description intent mismatches.
• AI Overviews / GEO criteria are a separate, stricter checklist — ask the user whether to apply them.

Inputs#

This skill needs two things, by whatever means are available:

• The list of pages in scope — a docs folder, a sitemap, or a doc graph.
• The content of each page — read on demand.

Acceleration (optional). Graph/semantic search over the docs makes navigation faster and cheaper than scanning files. You can self-host it with markdown-lsp, or get the same capability in the cloud by connecting a Docsbook workspace. With nothing connected, plain file reads and grep/find work fine. If you publish through a platform that exposes SEO settings (e.g. Docsbook PRO), the audit's recommendations can be applied there; otherwise they're plain edits to your markdown frontmatter.

Platform SEO switches#

Some platforms generate structured data (JSON-LD) for you — but behind opt-in switches that are often off by default. When they are off, the page still ships a basic TechArticle + Organization + BreadcrumbList graph, but the richest, most citable markup is withheld. Auditing frontmatter without checking these switches misses the biggest lever, so treat a disabled switch as a top-of-report finding.

On Docsbook, three workspace flags control this (read them with get_info; toggle from the SEO / GEO dashboard panel, or ask the agent to flip seoEnabled / geoEnabled / aeoEnabled):

Rule of thumb. If a workspace gets meaningful AI-crawler traffic (GPTBot, ClaudeBot, PerplexityBot in the logs) but aeoEnabled is off, that is almost always the #1 recommendation — the docs are being crawled but the most quotable structure is being withheld. Recommend enabling aeo (and geo for authored content), then verify the content actually has Q&A / step sections for the auto-detect to find (see the AI Overviews checklist below) — enabling the flag on prose with no detectable FAQ/HowTo adds speakable but no FAQPage, so the content work and the switch go together.

Caveat — don't blind-enable. FAQPage/HowTo are auto-detected heuristically. On pages with no genuine Q&A or procedure, forcing the markup risks invalid/irrelevant schema, which search engines can penalize. Flag the switch, but pair it with the content checks — enable where the content supports it, not blindly across every page.

Checklist#

Title (from frontmatter)#

• Present — every page has a title field
• 50-60 characters — longer gets truncated in SERP
• Unique — no two pages have the same title
• Primary keyword near the start — "Configure custom domain | Docsbook" not "Docsbook | Configure custom domain"
• Search intent — starts with a verb or question: "How to...", "Set up...", "Configure..."
• Brand suffix — "| Docsbook" for brand queries
• Not keyword-stuffed — one clear topic, not "Docsbook Custom Domain Setup Custom Domains"

Bad: title: Authentication Good: title: How to authenticate API requests | Docsbook

Description (from frontmatter)#

• Present — every page has a description field
• 130-160 characters — shorter is truncated, longer is cut in SERP
• Active voice — "Configure X to do Y" not "X can be configured"
• Includes primary keyword naturally
• Outcome-focused — "...in 5 minutes", "without CI/CD"
• A complete sentence — not a keyword list

Bad: description: API keys, auth, tokens, configure Good: description: Authenticate API requests to Docsbook using Bearer tokens. Get your API key from workspace settings in under a minute.

Heading Structure#

• One H1 per page — generated from frontmatter title (no # Heading in body)
• H2 → H3 → H4 in sequence — no level skipping
• Question-style H2 for FAQ-triggering sections: "How does X work?", "When should I use Y?"
• Keyword variations in H2/H3 — not exact repetition of title keyword
• Descriptive, not click-bait — "Configuration options" not "Let's get fancy"

Body Content#

• Minimum 300 words for competitive queries
• Primary keyword in first paragraph — naturally, not forced
• TL;DR / direct answer in first 2-3 sentences for AI Overviews
• Structured content — lists, tables — scannable for AI and humans
• Semantic variations — use synonyms and related terms naturally
• Date signals — last_reviewed or similar for freshness (technical pages)

Images#

• Alt text on all informative images
• Alt describes content + context — "Workspace settings panel with API key field highlighted"
• File names are descriptive — custom-domain-dns-records.png not screenshot1.png
• No alt stuffing — one natural description, not a keyword list

Internal Links (Topic Clusters)#

• Every page links to related pages — creates topic cluster
• Pillar pages (main topics) get inbound links from sub-pages
• Anchor text includes target keyword — "see the custom domain guide" not "see this guide"
• No orphan pages — every page has at least one inbound link

URL / File Path#

• kebab-case — custom-domain.md not customDomain.md
• Short and descriptive — /guides/custom-domain not /articles/2024/how-to-set-up-a-custom-domain
• Hierarchy reflects topic — /guides/integrations/github makes sense
• Stable — renames require redirects

AI Overviews / GEO Checklist#

Documentation increasingly appears in AI-generated answers (ChatGPT, Perplexity, Google AI Overviews):

• Direct answer in first paragraph — 2-3 sentences that stand alone
• Numbered lists for procedures — LLMs extract these cleanly
• Self-contained H2 sections — each section makes sense without reading the rest
• Definition format — "A workspace is a Docsbook container for one GitHub repository's documentation."
• Specific numbers — "under 30 seconds", "supports 15 languages", not "fast" and "many"
• Cited sources for non-obvious claims

What to Look For#

Output Format#

{
  "file": "docs/api/authentication.md",
  "line": 2,
  "severity": "high",
  "rule": "title-not-search-intent",
  "found": "title: 'Authentication' — this is a label, not a search intent. Users search 'how to authenticate API requests', not 'Authentication'.",
  "suggestion": "Change to: title: 'How to authenticate API requests | Docsbook' (52 chars, primary keyword near start)"
}

{
  "file": "docs/quick-start.md",
  "line": 3,
  "severity": "high",
  "rule": "description-too-long",
  "found": "description is 212 characters — will be truncated in SERP at 160 characters, losing the CTA.",
  "suggestion": "Shorten to 130-160 characters while keeping the primary keyword and outcome. Example: 'Create a documentation site from your GitHub repo in 30 seconds. No CI/CD, no configuration, no setup.' (112 chars)"
}

{
  "file": "docs/guides/custom-domain.md",
  "line": null,
  "severity": "high",
  "rule": "orphan-page",
  "found": "No other page links to docs/guides/custom-domain.md. It has no link equity and is invisible to most navigation flows.",
  "suggestion": "Add a link from docs/quick-start.md in 'Next steps': '[Set up a custom domain](/docs-skills/skills/guides/custom-domain)'. Also add to the PRO features overview page."
}

Acceptance Criteria#

• Platform SEO switches (seo/geo/aeo on Docsbook) have been read and any disabled switch is surfaced as a top finding — or noted as N/A if the platform has none.
• Every page in scope has been checked for title, description, and H1 completeness.
• Cross-page checks (duplicate titles, orphan pages) have been run against the full doc graph.
• AI Overviews / GEO criteria are either applied (user confirmed) or skipped with a note.
• Output is valid JSON per the format above, one object per finding.

Related Skills#

• docs-structure-templates — frontmatter structure overlaps
• docs-navigation-linking — topic clusters are an SEO + navigation concern
• docs-accessibility — alt text is shared between SEO and a11y
• docs-analyze — orchestrator