SEO for docs

AI answer engines got all the attention in 2025, but classic Google / Bing search still sends most of the qualified traffic to docs sites. The SEO playbook for docs is narrower than for marketing sites — you don't buy links, you don't run A/B tests on H1s, you don't chase long-tail keyword variants. What you DO is emit clean on-page signals so searchers looking for specific answers land on the page that has them.

This guide is the boring reliable playbook. For the generative-engine sibling, see GEO.

The on-page signals that matter

Google's ranking factors are hundreds of signals, but for a docs page the load-bearing ones are a handful:

What NookDocs emits automatically

Every tenant ships these with zero configuration — the defaults are SEO-correct. Verify once, then forget about them:

• <title> from page frontmatter title + site seo.title, format {Page} | {Site}.

• <meta name="description"> from frontmatter description, fallback to site seo.description.

• <link rel="canonical"> to the primary domain's absolute URL per page.

• <meta name="robots"> honouring seo.indexing site-wide + page hidden: true.

• /sitemap.xml at the docs root, regenerated on every page sync.

• /robots.txt at the docs root, references the sitemap.

• Open Graph + Twitter card tags from frontmatter fallback to site defaults.

• H1 from the frontmatter title — one per page, always.

See Optimize → SEO for the full config reference. The guide here is the thinking behind those defaults.

Title tag — the 50-60 char budget

Google truncates page titles at ~60 characters. NookDocs stitches your page title with your site name:

# Frontmatter
title: Add a custom domain

# Rendered <title>
Add a custom domain | Acme Documentation

The page title should stand on its own (user knows it's "Acme" from the site name). Patterns that work:

Patterns that don't:

Meta description — the 155-char pitch

Meta descriptions aren't a direct ranking factor (since ~2009) but they drive click-through, which affects ranking indirectly. Write each page's description as a self-contained pitch for that page:

# Good — specific, verb-first, names the affordance

description: "Add a CNAME record pointing to our edge, verify via the dashboard, and get auto-provisioned Let's Encrypt SSL in under 60 seconds."

# Bad — vague, reads like table of contents

description: "Learn about custom domains and how to set them up."

Aim for 140-160 chars. Google truncates longer; shorter wastes SERP real estate.

Heading hierarchy

One H1 per page (your page title). H2s are major sections. H3s are subsections. Don't skip levels (no H4 directly under H1).

# Add a custom domain              (H1 — from frontmatter)

## DNS setup                        (H2)
### CNAME for subdomain             (H3)
### ALIAS for apex                  (H3)

## SSL verification                 (H2)

## Troubleshooting                  (H2)
### DNS not propagating             (H3)
### CAA record blocking Let's Encrypt (H3)

Why this matters: Google's "People also ask" + "Things to know" SERP features scrape H2/H3 as candidate answers. Clear hierarchy = eligible for featured snippets.

Internal linking strategy

Topical clusters rank better than orphaned pages. Minimum viable cluster structure:

Descriptive anchor text ranks better than "click here":

❌ For more info, [click here](/deploy/custom-domain).
✅ See [adding a custom domain](/deploy/custom-domain) for DNS record specifics.

Keyword research for docs — narrower than marketing

Docs SEO isn't about finding clever long-tail keywords competitors missed. It's about naming things the way users search for them.

Sources for the actual queries your users type:

• Search Console "Performance" report. Queries your docs already surface for, even if on page 2-3. Rewrite pages to rank higher.

• Your own search bar analytics. What users type into your on-site search tells you the exact phrasing they expect. Analytics dashboard surfaces top queries.

• Support tickets + Slack questions. Every repeated question is a page that should exist.

• Reddit + Stack Overflow for your product. Phrases users use when asking the community to translate their problem.

Three things NOT to do:

• Keyword-stuffing — cramming a phrase into the page 20 times. Google's been on to this since 2003. Write natural prose.

• Long-tail page farming — spawning /add-custom-domain, /how-to-add-custom-domain, /custom-domain-setup-guide that all say the same thing. Canonicalise to one page.

• Exact-match domains — customdomainsetup.com. Users don't type domain names as queries anymore.

Schema.org JSON-LD (roadmap)

Schema.org JSON-LD is structured data Google uses to render SERP enhancements — breadcrumbs in the results, FAQ accordions, HowTo cards, video carousels. NookDocs doesn't emit these automatically yet (roadmap). When it lands the shape will be:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Add a custom domain",
  "description": "...",
  "author": { "@type": "Organization", "name": "Acme" },
  "datePublished": "2026-04-20",
  "dateModified": "2026-04-20"
}
</script>

Until then, the visible signals (title, description, canonical, sitemap) cover ~95% of docs-relevant SERP ranking. Schema is nice-to-have, not critical.

Indexing controls

Three levers, scoped differently:

• Site-wide seo.indexing: "noindex" — everything gets <meta name="robots" content="noindex, nofollow"> + Disallow: / in robots.txt. Use for staging and private docs.

• Per-page hidden: true frontmatter — drops the page from sitemap + search + llms.txt. Page still renders at its URL for anyone with the link.

• Per-page noindex: true frontmatter (if supported) — page renders + appears in sitemap but carries a robots noindex meta. Useful for gated flows where you want the URL discoverable but not indexed.

See Optimize → SEO for the config details.

Image SEO

Images rank in Google Images if you help them:

• Descriptive alt text, not just filename. alt="Dashboard showing the Custom Domains panel with two verified entries" beats alt="dashboard.png".

• Lowercase hyphenated filenames. custom-domain-dashboard.png beats IMG_2341.PNG.

• Near your heading. Images right below an H2 rank for that heading's keywords.

• Reasonable size. 1600×900 retina-friendly for hero images, 800×600 for inline, <300KB compressed.

See the dedicated media guide for the full image + video story.

Featured-snippet optimisation

Google's featured snippet ("People also ask", top-of-SERP answer box) pulls from the first passage after an H2 that matches a question-shaped query. To target:

## What is a CAA record?

A CAA (Certificate Authority Authorization) record is a DNS record
that tells certificate authorities which issuers are allowed to
issue SSL certificates for your domain. Add Let's Encrypt to your
CAA record before requesting SSL:

    acme.com.  IN  CAA  0 issue "letsencrypt.org"

The H2 phrases the exact query. The first paragraph is the answer. The code block is the actionable takeaway. Google's extractor loves this shape.

Common SEO mistakes in docs

Monthly SEO routine (30 minutes)

1. Search Console → Performance — sort queries by position. Queries in positions 5-20 are quick wins. Pick one, rewrite the page's H1/H2s to match the query language.

2. On-site search dashboard — top queries that returned 0 results. Each is a missing page. Add it.

3. Check for broken internal links — use a crawler or linkcheck script. Fix any 404s.

4. Freshness audit — pages not touched in 12+ months. Update the content even if the feature's unchanged — Google likes fresh dates. NookDocs shows "Last updated" automatically from git.

Related

• GEO — AI search optimization — the AI-engine sibling to classic SEO

• Optimize → SEO — the mechanics + config reference

• Style and tone — the voice that SEO rewards

• Content types — Diátaxis framework — smaller focused pages rank better

• llms.txt — complementary AI-crawler index