Skip to content

docs: stop six English pages competing with themselves in search - #471

Merged
marevol merged 2 commits into
masterfrom
fix/seo-en-duplicate-pages
Aug 8, 2026
Merged

docs: stop six English pages competing with themselves in search#471
marevol merged 2 commits into
masterfrom
fix/seo-en-duplicate-pages

Conversation

@marevol

@marevol marevol commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

Twelve English pages form six pairs that share a title, and every one of
them points at itself as canonical — so each pair competes for a single
search result and Google picks whichever it likes. These six pairs are the
only duplicate titles left across all 1,730 pages in the sitemap.

Five pairs are the same subject written twice

The shorter page exists only in English; the fuller one exists in all seven
languages.

English-only counterpart (7 languages) shared title sizes
config/analyzer config/admin-analyzer Analyzer Configuration 14 vs 77 lines
config/role-setting config/security-role Role-Based Search Configuration 51 vs 72
config/virtual-host config/security-virtual-host Virtual Host 50 vs 75
config/search-config config/search-advanced Search-Related Settings 177 vs 393
config/index-backup config/admin-index-backup Index Management 13 vs 372

Each shorter page now names the fuller one as its canonical:

:canonical: admin-analyzer

The URLs stay and the content stays — an existing link keeps working.
What changes is that the pair is consolidated onto the page that is
translated everywhere, instead of the choice being made for us.

The value is a document name resolved against the declaring page's own
directory, which is why the identical line works in 15.7 and in 15.8.
Cutting the next version copies the directory verbatim; a value carrying
15.7 would leave the copy pointing at the previous version, and nothing
would say so.

The sixth pair is not a duplicate

/api/api-suggest and /api/admin/api-admin-suggest are different APIs —
one returns suggest words to a searcher, the other manages them and
requires an admin access token — that happen to share the English title
Suggest API. Japanese already tells them apart (サジェストAPI /
Suggest API). The admin one is retitled Admin Suggest API, using
the wording already on the page beside it (Admin API Overview, "the Admin
API permission"). Its rules are resized to the new title.

Scale, stated plainly

These twelve pages drew 276 impressions and 4 clicks over three months
0.15% of the site's 187,000 impressions. This is tidying, not a traffic
measure. The cannibalisation is real (search-config 53 impressions +
search-advanced 39 = 92 impressions and zero clicks) but small.

Verification

  • python3 tools/check_headings.py en/15.7 en/15.8 → exit 0
  • python3 -m unittest discover -s tools -p 'test_*.py' → 23 tests, OK
  • Built the affected pages with the site's Sphinx version and confirmed the
    emitted <link rel="canonical"> points where intended, that
    admin-analyzer and the two suggest pages still point at themselves, and
    that titles, og:url and the generated meta descriptions are unchanged.
  • The :canonical: field is file-wide metadata: Sphinx removes it from the
    document, so it does not appear in any rendered page.

Reading the field is a change to the site generator; until that ships these
lines are inert metadata and the pages render exactly as they do today.

marevol added 2 commits August 8, 2026 21:28
14.19 reached end of life on 2026-08-01 but was still listed as supported,
so `tools/update_eol.py` reported it on every run. The tool leaves that
call to a person on purpose -- a version does not stop being supported
because a date passed while nobody was looking -- so this commit is that
decision: 14.19 moves from `supported` to `eol`, and `nearing` empties.

The schedule also carried 2018-02-30 for 10.2, a date that does not exist.
It has been there since the table was first written in 2017, when every one
of those rows was still in the future. eol.rst states the rule the schedule
follows -- end of life falls about eighteen months after release -- and the
neighbouring rows follow it exactly: 10.0.0, 10.1.0, 10.3.0 and 11.0.0 each
sit eighteen months after their release date. 10.2.0 was released on
2016-08-30, and eighteen months later lands in a February with no 30th.
Corrected to 2018-02-28, the last day that month has.

The generated tables in all seven translations were regenerated from
versions.json, and the 14.19 row in downloads.rst moved from the current
releases table to the end-of-life one, so the two pages no longer disagree
about which versions are current.

`python3 tools/update_eol.py --check` now exits 0 with nothing on stderr.
Twelve English pages form six pairs that share a title, and every one of
them points at itself as canonical, so each pair competes for a single
result and Google picks whichever it likes. Nothing else on the site does
this: the six remaining duplicate title groups across all 1,730 pages in
the sitemap are exactly these.

Five of the pairs are the same subject written twice. The shorter page
exists only in English; the fuller one exists in all seven languages:

    config/analyzer        ->  config/admin-analyzer
    config/role-setting    ->  config/security-role
    config/virtual-host    ->  config/security-virtual-host
    config/search-config   ->  config/search-advanced
    config/index-backup    ->  config/admin-index-backup

Each shorter page now names the fuller one as its canonical:

    :canonical: admin-analyzer

The URLs stay, and so does their content -- an incoming link keeps working.
What changes is that Google consolidates the pair onto the page that is
translated everywhere instead of choosing.

The value is a document name resolved against the declaring page's own
directory, which is why the same line works unchanged in 15.7 and in 15.8.
Cutting the next version copies the directory verbatim; a value carrying
"15.7" would leave the copy pointing at the previous version, and nothing
would say so.

The sixth pair is not a duplicate. /api/api-suggest and
/api/admin/api-admin-suggest are different APIs -- one returns suggest
words to a searcher, the other manages them and needs an admin token --
that happen to share the English title "Suggest API". Japanese already
tells them apart. The admin one is retitled "Admin Suggest API", matching
"Admin API Overview" alongside it.

Reading the canonical is a builder change; without it these lines are inert
metadata that Sphinx drops.
@marevol
marevol merged commit 531d1e8 into master Aug 8, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant