8 GitBook SEO Checks for Public Documentation Sites

GitBook handles much of the technical work behind a public documentation site, but the publishing settings and content still need checking. A page can be available by URL yet excluded from search, hidden from navigation yet publicly readable, or published with a canonical that names the wrong product version.

These eight GitBook SEO checks connect the relevant publishing controls to evidence you can inspect on the live site. They cover hosted GitBook documentation, including sites on a custom domain or under a path such as /docs. They do not apply to the deprecated GitBook CLI or a separate website styled to resemble GitBook.

The workflow is based on GitBook and Google documentation checked on October 30, 2026. The examples are illustrative; no customer site or account configuration was tested. Start with a small set of important pages: an onboarding guide, a troubleshooting answer, an API reference, and any older version or translation that should remain discoverable.

1. Confirm the audience and inherited indexing policy

First decide which pages belong in public search. An installation guide may need broad discovery; a beta announcement may be publicly readable without appearing in search; an internal runbook needs an access restriction.

GitBook separates several controls that can look similar during an audit:

The public publishing documentation describes separate internal and external page controls. It also describes inheritance: disabling search indexing on a parent disables it for descendants, and a child cannot re-enable it. If an intended search landing page is excluded, inspect its parents before repeatedly editing the child.

Check control availability in your site's current plan. The publishing guide still uses a “Premium” plan label, while the current pricing matrix uses Essential, Ultimate and Enterprise for site-wide search opt-out. That matrix does not separately establish the exact entitlement for every page-level control. A missing control needs an account or plan check, not an assumed tier upgrade.

After a change, inspect the public response and its robots directives. A noindex rule must be accessible to Googlebot for Google to read it; blocking crawling can prevent that. Screpy's guide to noindex and nofollow explains the distinction.

Neither navigation hiding nor search exclusion protects confidential information. GitBook explicitly says hidden pages remain available through its published MCP server and llms-full.txt; use an appropriate access method when content must be restricted.

2. Give each page a specific title and description

Read a page title outside its sidebar. “Overview” makes sense while browsing an Authentication section, but “Acme API authentication overview” tells a search visitor which product and task the page covers.

GitBook's SEO reference says HTML and Open Graph titles use the page and site titles, while descriptions use the page description. Change those inputs, then inspect the resulting tags rather than assuming the editor text is the complete HTML title.

For example, a webhook guide could use:

A separate link title keeps navigation concise without forcing the main title to be vague. GitBook documents this under Edit title & slug in its page controls. If the existing public URL must stay stable, confirm its manually configured slug before changing the title; check 5 covers URL changes.

For your important pages, inspect <title>, meta[name="description"], og:title and og:description in the published HTML. Look for a missing description, repeated site name, an obsolete product version, or identical text across unrelated guides. Check the visible heading too: a correct metadata field cannot repair instructions for the wrong task.

These fields describe the page to search engines and sharing clients. Google chooses title links and snippets automatically, so your preferred wording is not guaranteed to appear verbatim.

3. Check canonicals for versions and translations

A documentation version is not automatically a duplicate. If an older API requires a different authentication method, its instructions may still deserve their own search landing page.

In Page options → Metadata, GitBook lets you set canonical and alternate URLs, using another page or an external URL. Before changing either field, decide what relationship actually exists:

Open both the source page and its intended canonical target. Check that the target is the right document, returns a successful response, and is eligible for the search visibility you intend. A link to the documentation homepage is usually an inadequate substitute for an equivalent task page.

Google treats canonical declarations as signals, not an instruction it must always follow. Its canonicalization guidance applies to duplicate or very similar pages; Screpy's canonical tag guide covers common conflicting signals.

For translated pages, inspect the generated alternate tags. A field named “Alternate URLs” does not by itself establish that the output meets Google's hreflang requirements. Verify the actual language codes, equivalent destinations and reciprocal references against Google's localized-page guidance. Do not add language annotations to unrelated version pages merely because both are called variants in the editor.

4. Open the sitemap at the real site home

GitBook's current SEO reference gives /sitemap-pages.xml as the page sitemap location for published sites that are not unlisted. Use your documentation site's actual home URL, including its path prefix:

Site home: https://docs.example.com/
Sitemap:   https://docs.example.com/sitemap-pages.xml

Site home: https://www.example.com/docs/
Sitemap:   https://www.example.com/docs/sitemap-pages.xml

For a live example of that structure, GitBook publishes its own documentation page sitemap. Older tutorials may suggest /sitemap.xml; a failed request at an old path does not establish that the current sitemap is missing.

Fetch the file and inspect its contents. A successful HTTP response that contains an HTML error page is not a valid XML sitemap. If a sitemap index is returned, follow its listed child sitemaps before concluding that a page is absent.

Compare the discovered URLs with the important pages selected for this audit. For each missing guide, check publication, its section or variant, and indexing policy. For an unwanted URL, inspect its actual response and canonical before changing controls. Do not assume that every custom exclusion has produced the XML you intended.

A useful comparison records three things: the expected public URL, whether it appears in the XML, and the reason for any difference. Also look for an old hostname, a missing /docs prefix, or a redirecting URL left after a reorganization.

Keep the preferred URL consistent across the sitemap, canonical and internal links. Screpy's XML sitemap audit guide explains how to investigate mismatches. Sitemap inclusion helps discovery; it does not establish that Google indexed the page.

5. Protect public URLs when reorganizing docs

A Git Sync file path is not the published URL contract. GitBook builds public paths from the navigation tree, including ancestor and group slugs. Renaming a group can therefore change many child URLs even when their Markdown filenames stay the same.

Before editing titles or moving content, record the current public URLs and intended destinations. Set a stable page slug manually when a clearer title should leave the address unchanged. Include links from your product UI, support replies and release notes in this review; those destinations may be outside the docs sidebar.

GitBook's redirect documentation distinguishes automatic and manual behavior. Moving or renaming pages creates automatic 307 redirects. Manual site redirects can be temporary 307 or permanent 308, and a draft rule has no live effect until enabled. Selecting a destination page stores a reference that can survive later page moves; a fixed path does not have that advantage.

Check the response as an anonymous visitor. For manual permanent rules, GitBook documents 308 for live public content, while app, preview and visitor-authenticated requests receive 307. Looking only at an editor preview can therefore give the wrong impression.

For a page that moved, these Windows commands save the first response and show the final destination:

curl.exe --silent --show-error --dump-header old.headers --output old.body "https://docs.example.com/old-guide"
curl.exe --silent --show-error --location --output destination.html --write-out "%{http_code} %{url_effective}\n" "https://docs.example.com/old-guide"

Replace the example URL first. Inspect old.headers for the initial status and Location, then verify that the final page contains the intended guide rather than a generic homepage or an error message.

Do not assume a manual rule overrides an automatic redirect. GitBook resolves content and automatic redirects before section-level and site-level rules. If the observed destination is wrong, investigate that resolution order instead of adding repeated rules. Finally, update internal links to the intended destination so a redirect is not the normal path through your docs.

6. Keep important pages linked from useful entry points

A page can exist in the sitemap while being hard for a reader to find. Follow the actual published navigation from your docs home to each important guide. Then follow the contextual links that connect prerequisites, setup, reference material and troubleshooting.

For a webhook feature, a useful path might be:

Getting started → Create a webhook → Configure retries
                                      ↓
                             Diagnose failed deliveries

Each destination should answer the next likely question. Link “diagnose failed webhook deliveries” where that task becomes relevant, rather than adding repeated “click here” links to unrelated paragraphs.

Inspect the link destination, not just the clickable styling. Google's link guidance recommends actual <a> elements with href values that identify the target. A search box or interactive button is not evidence that an equivalent crawlable path exists in the page.

Review fragment links too. GitBook's heading controls allow custom anchors. Set a stable anchor when external support material or product screens link directly to a section whose heading may change. After an edit, open the full URL with its fragment and confirm that it still reaches the right instructions.

A page intentionally hidden from the table of contents may still need a contextual link from another public page. Make that a deliberate publishing choice. When a link fails, record its source page and anchor text before repairing it; Screpy's broken internal link workflow explains how to preserve that context during an audit.

7. Check the published answer and its media

Choose a real reader task and try to complete it from the public page. For the webhook example, the reader should be able to find the supported retry behavior, configure it, and understand what happens when delivery still fails. A polished heading above an outdated screenshot does not complete that task.

GitBook documents pre-rendered HTML for published sites. Check that the response contains the useful answer in the document content, including essential text and code, rather than relying on a match inside a script or serialized application data. Compare it with the visible page after publication: an editor change that has not reached the public site is not ready for this audit.

Keep the heading outline understandable. GitBook's page title is separate from body heading blocks, and its Markdown representation places body headings below the page title. Inspect the resulting hierarchy instead of assuming a heading label in the editor maps directly to the same HTML level.

For a screenshot that explains a setting, confirm that the setting still exists and that surrounding text describes the action. GitBook's image block controls support alt text and captions. Use an alternative that conveys the relevant image information; avoid repeating a target keyword on every screenshot.

Also read the guide on a narrow viewport. Check tables, long commands, image labels and code copying. If you use separate light and dark images, inspect both for legibility. Large media can slow a page, so remove an unnecessary animation or resize an oversized screenshot when it interferes with the task. A responsive platform does not by itself prove that your particular page is comfortable to use.

Update inaccurate instructions when the product changes. Record that substantive change in your release notes rather than changing dates merely to make an unchanged page look newer.

8. Record Google evidence after the release

Once the public pages pass the earlier checks, inspect their final URLs in a Search Console property you control. A page appearing in GitBook search or Ask AI does not establish that Google indexed it; those are separate systems.

For a custom hostname such as docs.example.com, use a property that covers it. A verified domain property covers its subdomains; a URL-prefix property must match the relevant protocol, host and path. Follow Google's ownership verification process rather than trying to submit a URL outside your control.

Use URL Inspection to read the available Google indexing state and canonical information. When diagnosing the current page, use its live test as additional evidence; the live result and Google's stored indexed state answer different questions. For a small number of important new or changed URLs, an owner or full user can request indexing. For a larger set, submit the verified sitemap.

Google's recrawl guidance makes clear that a request does not guarantee inclusion or immediate processing, and repeated requests for the same URL do not speed crawling. Keep “request accepted” separate from “page indexed” in your record.

Copy this CSV into your own release worksheet and replace the example URLs. The observed and evidence fields are intentionally empty:

check_id,page_url,expected,observed,evidence,owner
1,https://docs.example.com/webhooks/retries,Public access and intended external indexing policy,,,
2,https://docs.example.com/webhooks/retries,Specific published title and description,,,
3,https://docs.example.com/webhooks/retries,Canonical matches the intended equivalent document,,,
4,https://docs.example.com/webhooks/retries,Preferred URL present in the verified sitemap,,,
5,https://docs.example.com/old-retry-guide,Old URL reaches the intended current guide,,,
6,https://docs.example.com/webhooks/retries,Reachable from relevant public navigation and links,,,
7,https://docs.example.com/webhooks/retries,Current usable answer with readable code and media,,,
8,https://docs.example.com/webhooks/retries,Google inspection state recorded separately from requests,,,

For evidence, save the relevant response headers, HTML tags, sitemap entry, source link or dated Search Console observation. Assign an owner to unresolved issues. If a check cannot be completed because a control or account permission is unavailable, record that limitation instead of marking it passed.