Skip to content

docs: cut the subtitle from the guide article titles - #469

Merged
marevol merged 1 commit into
masterfrom
fix/seo-article-titles
Aug 8, 2026
Merged

docs: cut the subtitle from the guide article titles#469
marevol merged 1 commit into
masterfrom
fix/seo-article-titles

Conversation

@marevol

@marevol marevol commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

The 23-part guide series carries a subtitle after a -- in every title, which puts them between 80 and 190 characters. A search result shows nothing like that much, so what a searcher actually sees is the series number and the first few words of the topic, cut mid-phrase.

Why these pages

Measured in Search Console over the last three months:

impressions clicks CTR position
whole site 187,000 6,140 3.3% 9.9
article pages (194) 17,900 260 1.5% 9.6

The articles rank where the rest of the site ranks and convert at less than half the rate. Ranking is not the problem; the result listing is. For scale, this is ten times the impressions of the description-less hub pages fixed in #468.

What changed

The subtitle is dropped from the heading and the over/underline rules are resized to the new title's display width. The series number stays, so the parts still read as a series. Nothing is reworded.

Part 9: Search Infrastructure for Multilingual Organizations -- Building an
Environment to Properly Search Documents in Japanese, English, and Chinese
      ↓
Part 9: Search Infrastructure for Multilingual Organizations

Scope is guide-*.rst — 161 files, 23 guides across 7 languages.

article-*.rst is deliberately excluded. There the text after the separator is what tells the four articles apart (installation, API, FSS), so removing it would leave each language with four pages under a single title. en/articles/article-4.rst uses the same -- separator and is excluded for this reason.

The information is not lost: each guide opens with an Introduction that already states what the subtitle said.

Result

Measured by display width, not character count — Google truncates on width, and a character count understates CJK by about half, so a 35-character Japanese title takes the room of a 70-character English one while a character count still calls it short.

before after
article titles wider than 60 columns 177 52

Of the 52 that remain:

  • 31 are guides whose main title alone is long — all in German, English, Spanish or French. Rewording them was out of scope for this change. Listed below so the decision is explicit.
  • 21 are the excluded article series and its siblings.

Every Japanese, Korean and Chinese guide title now fits.

The 31 guides still over 60 columns

By language: French 12, Spanish 10, German 5, English 4. The widest are fr/articles/guide-22 (108), es/articles/guide-22 (95) and fr/articles/guide-23 (95). In each case the topic itself is long in that language; shortening it means rewording, not cutting.

Verification

  • tools/check_headings.py is clean across every article directory, not only the current versions.
  • No new duplicate title within any language (checked across all 203 article files).
  • All 161 changed pages still generate a non-empty description under 200 characters with no markup leak.
  • Only the title and its two rule lines changed in each file; no body text was touched and no file was deleted.

Found while doing this, not fixed here

31 Japanese and Chinese article pages render a visible space between two CJK characters in their body text. The source writes one sentence per line inside a paragraph, and docutils turns that line break into a space. It is pre-existing — this branch touches only heading lines — and it affects 569 line pairs across 55 files. The generated meta description is unaffected because the generator strips those spaces, so this is a readability defect rather than a search one, and it is large enough to deserve its own change.

The 23-part guide series titles each carry a subtitle after a `--`, which
puts them between 80 and 190 characters. A search result shows nothing
like that much, so what a searcher sees is the series number and the
first few words of the topic, cut mid-phrase.

Measured in Search Console over the last three months, the article pages
draw 17,900 impressions -- 9.6% of the site -- at an average position of
9.6, which is the same as the site as a whole, but convert at 1.5% CTR
against the site's 3.3%. Ranking is not the problem; the result listing
is.

The subtitle is dropped from the heading and the rules are resized to the
new title's display width. The series number is kept, so the parts still
read as a series. Nothing is reworded.

Scope is `guide-*.rst`. `article-*.rst` is deliberately excluded: there
the text after the separator is what tells the four articles apart
(installation, API, FSS), so removing it would leave each language with
four pages under one title.

The information is not lost. Each guide opens with an Introduction that
already states what the subtitle said.

Result, measured by display width rather than character count -- Google
truncates on width, and a character count understates CJK by half:
article titles wider than 60 columns fall from 177 to 52. Of the 52, 31
are guides whose main title alone is long, all of them in German,
English, Spanish or French; 21 are the excluded article series. Every
Japanese, Korean and Chinese guide title now fits.

No new duplicate title is created, and `tools/check_headings.py` is clean
across every article directory.
@marevol
marevol merged commit 4c53ec4 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