How to improve documentation SEO

Titles, descriptions, headings and internal links that rank, and the technical SEO Reed emits for you.

Search is still one of the most dependable ways people find documentation. When someone types “how to set up authentication with [your product]”, a well-written page can be the first result — ahead of a stale forum answer or a competitor’s tutorial.

Almost none of that is configuration. It comes from titles, headings, links and freshness, which are editorial decisions. Reed handles the technical layer; the rest of this page is about the part only you can do.

Write titles and descriptions that rank

The page title is the strongest on-page signal you have. It tells both the search engine and the person scanning results what the page covers.

Titles: 50–60 characters

Write the title the way people search, not the way your product’s UI labels things. “Authentication” is a menu item. “How to authenticate API requests” is a query.

Match intent: “how to”, “guide” and “reference” each signal a different kind of page.
Put the main keyword near the start.
Keep every title unique. Two pages with the same title compete with each other.

Descriptions: 130–160 characters

The description is the text under your title in a results page. At equal rank, a better description gets the click.

Say what the reader can accomplish, not just what the page contains.
Use the main keyword where it reads naturally.
Write actively: “Configure webhooks to…” rather than “This page explains…”.
Put the answer in the first 120 characters. Reed’s llms.txt truncates a description after 120; the rest still serves the meta description.

On Reed, both come from frontmatter:

1
---
2
title: How to authenticate API requests
3
description: Send your API key as a bearer token in the Authorization header, with examples in JavaScript, Python and curl.
4
---

title becomes the page’s H1. description becomes the meta description, the description in the page’s generated structured data (emitted only when site is set), and its entry in llms.txt. Site-wide defaults — the Open Graph image, type, site name and locale, Twitter handles, and robots directives — live under seo in docs.json. See Addressing, head and SEO.

Do keyword research for your docs

Keyword research tells you what people actually type when they need what your page covers — which is often not what your team calls it.

Start with your own data. If your docs domain is verified in Google Search Console, open the performance report. The best targets are queries you already appear for, and especially queries where you appear but rank poorly.

Find related queries. Free tools such as Google Keyword Planner and Ahrefs’ free keyword generator show search volume and suggest adjacent phrasings.

Where keywords belong

The page title and description — highest impact.
## and ### headings.
The first paragraph.
Alt text, where the keyword genuinely describes the image.

Do not repeat keywords mechanically. Documentation has to read naturally. If a heading sounds forced, the keyword is wrong for that section.

Structure pages with headings search engines can parse

Headings do two jobs: they let readers scan, and they tell search engines how the topics on a page relate.

Reed renders your frontmatter title as the H1. Never write another one in the body; start at ## and descend one level at a time:

1
## Main section
2

3
### Subsection
4

5
#### Detail, used sparingly

An H1 in the body, or a jump from ## to ####, is DS-A02 — an error that reed check reports before anything is published.

Phrase headings as questions or intents where it fits.

Weak heading	Stronger heading
Authentication	How authentication works
Rate limits	Understanding API rate limits
Configuration	How to configure your integration

Question-shaped headings are also more likely to appear in Google’s “People also ask” boxes, which sit above organic results and earn clicks even for pages that do not rank first.

Internal links help search engines find your pages, understand what they are about, and pass authority between them.

Link concepts where they come up. When one explanation depends on another, link to it with anchor text that says what the reader will find:

1
Learn how Reed [builds your sitemap and robots.txt](/docs/site/discovery).

Not:

1
[Click here](/docs/site/discovery) to learn more.

Write the base prefix yourself. On a site with base set, Reed does not rewrite links in prose. A link written as /quickstart on a site mounted at /docs compiles cleanly and 404s in production — and a crawler that follows it finds nothing. reed check does not validate prose links, so check them mechanically; this site runs a small script over its content on every change. See Linking and site and base.

Find orphans. A page nothing links to is hard for search engines to discover. On Reed, every page must be listed in navigation — there are no hidden pages, and a file left out fails reed check — so the sidebar already reaches every page. What it cannot do is connect pages to each other, so check that the important ones are also linked from the prose around them.

Build topic clusters. The getting-started page links to the authentication guide, which links to the API keys reference, which links back to the overview. A tight cluster tells a search engine these pages cover one subject in depth.

Add alt text to images

Alt text serves accessibility and search at once. Search engines cannot interpret an image; its alt text is the only way it contributes to the page’s relevance.

Describe what the image shows, in context:

1
![Token exchange between the client, the auth server and the API](https://cdn.example.com/auth-flow.png)

Not:

1
![Diagram](https://cdn.example.com/auth-flow.png)

Use a keyword only where it actually describes the picture. On Reed, an image with no alt text at all is DS-A01, an error. See Media.

Technical SEO Reed handles

Reed emits the technical foundation at build time. Most of it depends on one setting: site, the absolute origin your docs are served from. Reed never guesses it.

Sitemap. With site set, every build writes sitemap-index.xml and sitemap-0.xml. Submit the index to Google Search Console.
robots.txt. Also gated on site. It allows every user agent and points at the sitemap. seo.robots.index: false switches it to Disallow: / and marks every page noindex — useful for a staging deployment.
Canonical URLs. Derived from site and base on every page. There is no seo.canonical override.
Meta tags. Description, Open Graph and Twitter card tags from your frontmatter and the seo block.
Structured data. A TechArticle object per page by default when site is set, plus anything you add through jsonLd. See Structured data.
Semantic HTML and responsive layout. Heading hierarchy, navigation landmarks, and pages that work on a phone.

If site is unset, no sitemap, robots.txt, canonical URL or per-page structured data is written. That is deliberate: a sitemap of guessed URLs is worse than none, because search engines act on it. Set site before you launch. See site and base and Discovery.

A few things Reed does not do: there are no per-page robots overrides in frontmatter and no custom robots.txt. head.meta and head.link inject extra data-only tags on every page when you need a verification tag or similar — see head injection.

Keep documentation current

Freshness is a ranking signal, particularly for pages about things that change: API references, configuration guides, integration instructions.

Update the docs in the same pull request that ships the feature.
Review your highest-traffic pages every quarter.
Run reed check and a link check before every publish, in CI, so broken pages never ship. See Offline builds in CI.

Stale docs cost you twice. They rank worse, and a reader who arrives from search to find wrong information stops trusting everything else you wrote. Maintenance covers keeping a docs set accurate over time.

Monitor search performance

Reed has no analytics dashboard. For search data, verify your docs domain in Google Search Console — a head.meta entry is enough for the HTML-tag verification method. It shows you:

Impressions and clicks: which pages appear in results, and how often they are chosen.
Average position: where each page ranks for a given query.
Queries: the exact terms that bring people in — your best source of new keywords.

Check it monthly. Two patterns deserve attention first: pages with many impressions but few clicks, whose titles or descriptions are not persuasive, and pages that rank low for queries that matter, which usually need more substance. For on-site traffic, Reed’s analytics block wires in one of a fixed set of providers.

Frequently asked questions

How long should a documentation page be?

Long enough to finish the task, short enough to stay on one topic. A getting-started guide might be 800 words and an API reference 3,000. If readers routinely have to go elsewhere to complete what the page started, it is too thin. Very short pages — under about 300 words — rarely rank for competitive queries.

Is documentation SEO different from blog SEO?

The principles are the same: relevant titles, clean structure, internal links. Docs have an edge on long-tail queries such as “how to configure OAuth with [product]”, where competition is thin, and developers link to docs naturally from issues, answers and forums. Favor specificity and accuracy over volume.

How do I submit my sitemap to Google?

Set site in docs.json so Reed writes one. Then, in Google Search Console, open Sitemaps and enter the URL of sitemap-index.xml under your site origin and base path. Submitting speeds up discovery; it does not guarantee indexing.

How often should I update pages for SEO?

Whenever the product changes — accuracy is the signal that matters most. Beyond that, review pages untouched for a year, and use Search Console to find pages losing traffic or position. Those are the first candidates for a refresh.

What is the difference between SEO and GEO?

SEO is about ranking in search engines like Google and Bing. GEO is about being cited by AI tools like ChatGPT, Perplexity and Google AI Overviews. Accurate, well-structured content does well in both; GEO adds practices for making content easy to excerpt. The GEO guide covers them.

Does Reed handle SEO automatically?

The technical part, yes — sitemap, robots.txt, canonical URLs, meta tags, structured data and semantic HTML, once site is set. It cannot write better titles, research keywords, link your pages together or fill out thin content. Those are editorial decisions, and they are most of the work.