--- title: How to improve documentation SEO description: 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: ```mdx --- title: How to authenticate API requests description: Send your API key as a bearer token in the Authorization header, with examples in JavaScript, Python and curl. --- ``` `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](/docs/reference/docs-json/site). ## 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: ```mdx ## Main section ### Subsection #### Detail, used sparingly ``` An H1 in the body, or a jump from `##` to `####`, is `DS-A02` — an error that [`reed check`](/docs/reference/cli/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. ## Link related pages to each other 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: ```mdx Learn how Reed [builds your sitemap and robots.txt](/docs/site/discovery). ``` Not: ```mdx [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](/docs/guides/linking) and [site and base](/docs/site/addressing). **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: ```mdx ![Token exchange between the client, the auth server and the API](https://cdn.example.com/auth-flow.png) ``` Not: ```mdx ![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](/docs/guides/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](/docs/site/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](/docs/site/addressing) and [Discovery](/docs/site/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](/docs/site/head). ## 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](/docs/ship/ci-offline). 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](/docs/guides/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`](/docs/site/analytics) block wires in one of a fixed set of providers. ## Frequently asked questions 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. 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. 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. 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. 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. 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. ## Related guides - [GEO: optimize docs for AI search and answer engines](/docs/guides/geo) - [Linking](/docs/guides/linking) - [Improving your docs](/docs/guides/improving-docs)