Docsbook
Overview

SEO

Docsbook builds the machine-readable half of your documentation for you. Every page it hosts is server-rendered HTML carrying a resolved <title>, a cleaned meta description, one canonical URL, an hreflang set that contains only languages you have really translated into, OpenGraph and X cards with a generated image, a JSON-LD graph, and an entry in a sitemap that robots.txt points at. You write Markdown; the head is a consequence.

This section covers search results — what Google and Bing crawl, index and rank. Two neighbours cover the other machine surfaces and do not overlap with it: AEO is the answer box above the results, and GEO is being cited by an AI assistant instead of ranked.

What it costs you#

One thing.

  1. Write one clear # H1 and an opening paragraph that answers the page's question. They become the title and the description unless you override them.
  2. Nothing else. Canonical URLs, the sitemap, robots.txt, cards, JSON-LD and the language cluster are managed, and there is no configuration surface for them.

There used to be a switch here, and turning it on was step one. SEO was a per-project toggle in Settings ▸ SEO & GEO, off on a new project, and while it was off every page was served noindex, nofollow — every signal generated, all of them saying "do not index me". It was the single most common reason a Docsbook site was not in Google: on 14 September 2026, two thirds of all projects had it off. The switch is gone and the tab with it. Every project is indexable, and the only opt-outs are per page (noindex: true, below) or the whole project going private.

To override the generated line for one page, put it in frontmatter:

---
title: "Configure a webhook"
description: "Register a Docsbook webhook, choose its events, and verify the first delivery."
---

To keep one page out of the index while leaving it published and readable:

---
noindex: true
---

robots: noindex, noindex: yes and noindex: 1 are accepted too. Use it on pages that spend crawl budget without ever earning a click — a 90,000-character changelog, internal working notes, an unfinished placeholder. This is the only index opt-out there is now — there is no site-wide switch to reach for, and the whole-project equivalent is making the project private, which stops it being readable at all.

The signals, and where each one is decided#

Signal What Docsbook does Where
<title> Frontmatter title → body H1 → file name; workspace name appended exactly once How it works
<meta description> Frontmatter description → opening paragraphs, stripped of markup, at 160 characters How it works
Canonical URL Custom domain → product path → apex short path → owner subdomain; never a URL that redirects How it works
hreflang Only locales this page is genuinely translated into, plus x-default How it works
OpenGraph / X card summary_large_image with a generated 1200×630 image per page How it works
Robots directives Preview build → page noindex, in that precedence How it works
sitemap.xml Every page plus real translations, lastmod from the source commit How it works
JSON-LD Organization + TechArticle + BreadcrumbList on every page How it works
Discovery and re-crawl Sitemap, robots.txt, IndexNow push, cache timers Indexing
Google positions Search Console read into the admin panel, free on every plan Indexing

Why this is the right way (evidence)#

What Docsbook does Why it works on the crawler Source
Serves complete server-rendered HTML Google renders JavaScript in a queue where a page "may stay… for a few seconds, but it can take longer", and "not all bots can run JavaScript" JavaScript SEO basics
Gives every page its own title and description Google's title-link sources begin with "Content in <title> elements"; and "Identical or similar descriptions on every page of a site aren't helpful" Title links, Snippets
Points canonical at the URL that answers 200 rel="canonical" is "a strong signal that the specified URL should become canonical" — a signal Google can only follow if the target resolves Consolidate duplicate URLs
Lists only real translations in hreflang "If page X links to page Y, page Y must link back to page X. If this is not the case… those annotations may be ignored" Localized versions
Uses real commit dates for lastmod Google uses <lastmod> "if it's consistently and verifiably… accurate" Build a sitemap
Emits FAQPage / HowTo only when the page has that content "don't add structured data about information that is not visible to the user, even if the information is accurate" Intro to structured data
Renders the sidebar as HTML links on every page Crawl budget is spent on what is reachable; "If many of these URLs are duplicates… this wastes a lot of Google crawling time on your site" Crawl budget
Serves a 308 when a page moves A temporary redirect would leave the dead URL as the canonical one Consolidate duplicate URLs

What Docsbook will not claim#

  • None of this makes a page rank. Every mechanism above makes a page crawlable, unambiguous and correctly presented. Google's page-experience FAQ answers "Is there a single 'page experience signal'…?" with "There is no single signal", and answers how much page experience matters to ranking with "Google Search always seeks to show the most relevant content, even if the page experience is sub-par" (Page experience). Markup is the floor, not the lever.
  • Structured data is documented as an eligibility signal, not a ranking one. Google's own introduction talks about rich results and says nothing about rank.
  • priority and changefreq in the sitemap do nothing for Google. "Google ignores <priority> and <changefreq> values." Docsbook emits them for the engines that do read them.
  • Crawl budget is probably not your problem. Google's crawl-budget guide is addressed to "Large sites (1 million+ unique pages) with content that changes moderately often (once a week)" and "Medium or larger sites (10,000+ unique pages) with very rapidly changing content (daily)" — and says in the same breath that these "are a rough estimate to help you classify your site. These are not exact thresholds." noindex on a huge changelog is still worth doing; treating a 60-page docs site as a crawl budget emergency is not.
  • No multiplier. Traffic depends on your topic, your competition and your domain. Any platform quoting you a percentage is quoting you someone else's site.

Limits#

  • There is no "index this section, not that one" control. The granularity is the whole project (private, i.e. unreadable) or one page (noindex: true) — nothing in between.
  • On a custom domain, per-page noindex is not honoured — pages are served index, follow unconditionally — and there is no hreflang cluster, no BreadcrumbList, no sitemap, no moved-page redirect and none of the GEO page-level signals. The canonical URL, title, description, cards and TechArticle node are all correct there. See How it works.
  • Search Console positions cover Docsbook-hosted hosts only. A site on your own domain is outside the property Docsbook reads. See Indexing.
  • A rename outside Docsbook leaves no redirect. Moves made through Docsbook write one automatically; a git mv does not.

Checklist#

  • Every page has one clear # H1, or a frontmatter title.
  • The opening paragraph answers the page's question in one or two sentences.
  • Every page is reachable from the sidebar; no orphans.
  • Pages that should never rank carry noindex: true.
  • For multilingual docs, translations are enabled so each language earns its own indexable URL.

Updated

Was this page helpful?