docs: give the 63 pages that ship no meta description an opening sentence - #468
Merged
Conversation
The Japanese and Chinese intro paragraphs added to documentation.rst and archives.rst wrap mid-sentence without the trailing backslash, so docutils keeps the line break and the rendered page shows a space between two CJK characters -- "API、 各種設定" and "ドキュメントを バージョンごとに" are live today. fess-docs-builder now strips that space from the generated meta description, but not from the page body, which is what a reader sees. Escaping the break at the source fixes both. Korean is left alone on purpose: it separates its words with spaces, so a wrapped line there renders correctly.
Nine pages per language are a heading followed by a toctree and nothing else. The description generator skips toctree nodes, so it collected no text and those pages shipped no meta description at all -- 63 of the pages in the sitemap. Google has to invent a snippet for them, and on a page whose body is a list of links there is little to invent from. Measured in Search Console over the last three months, these pages draw 1,810 impressions and 71 clicks at an average position of 7.4. They are already on the first page; only the snippet was missing. The two worst are the English administration index (270 impressions, 1.1% CTR) and the English tutorial page (73 impressions, 1.4%). Each page gains one sentence naming what it indexes. The wording is taken from the vocabulary each language already settled on in its own documentation.rst and archives.rst, and from the toctree the page actually carries, so nothing here introduces a new term. The 15.7 and 15.8 copies of the four in-version guides are identical files, so both get the same sentence. Japanese and Chinese lines that wrap end with the backslash this repository already uses for the purpose. Without it docutils keeps the line break, which becomes a visible space between two CJK characters in the rendered page. Verified: all 91 pages now produce a non-empty description, none over 200 characters, no two different pages share one, and no rendered paragraph contains a space between two CJK characters.
`overview.rst` is the section that gathers downloads, the quick start, screenshots and the demo. English, Korean and Chinese title it Overview. Japanese, German, Spanish and French translated it as "General", which is a different word: it is also the title of the administration screen's General settings page, so each of those four languages published two unrelated pages under one title and a search result could not tell them apart. The four are brought into line with the other three. The General settings page keeps its name, which is the correct one for it. These seven files also carry their opening sentence, from the change before this one -- the two edits are in the same paragraph block and are not worth separating.
marevol
force-pushed
the
fix/seo-followup
branch
from
August 8, 2026 08:37
0545903 to
54148ec
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Sixty-three pages in the sitemap ship no
meta descriptionat all. This gives them one, and fixes two smaller things found alongside.The pages, and why they were empty
Nine pages per language are a heading followed by a toctree and nothing else — the four in-version guide indexes (
admin,api,install,user) and the five top-level sections (overview,tutorial,basic,development,others). The description generator skips toctree nodes, so it collected no text and emitted no tag. Google then has to invent a snippet, and on a page whose body is a list of links there is not much to invent from.They are not obscure pages. Measured in Search Console over the last three months:
ja/15.7/install/index15.7/admin/index(English)ja/developmenttutorial(English)Average position across the set is 7.4 — they already rank on the first page. Only the snippet was missing, and the two English pages are visibly behind their Japanese counterparts.
What each page gained
One sentence naming what it indexes. The wording is taken from the vocabulary each language already settled on in its own
documentation.rstandarchives.rst, and from the toctree the page actually carries, so no new terminology is introduced. The 15.7 and 15.8 copies of the four in-version guides are byte-identical files, so both get the same sentence.Japanese and Chinese lines that wrap end with the backslash this repository already uses. Without it docutils keeps the line break, which becomes a visible space between two CJK characters in the rendered page.
Two things found alongside
The overview page was titled "General" in four languages.
overview.rstgathers downloads, the quick start, screenshots and the demo; English, Korean and Chinese title it Overview. Japanese, German, Spanish and French translated it as "General" — which is also the title of the administration screen's General settings page, so each of those four languages published two unrelated pages under one title. The four are brought into line with the other three; the settings page keeps its name, which is the correct one for it.#465 left a visible space in four pages. The Japanese and Chinese intro paragraphs added to
documentation.rstandarchives.rstwrap mid-sentence without the trailing backslash, soAPI、 各種設定andドキュメントを バージョンごとにare live today. fess-docs-builder now strips that space from the generated description but not from the page body, which is what a reader sees; escaping the break at the source fixes both. Korean is deliberately untouched — it separates its words with spaces, so a wrapped line there renders correctly.Verification
Every one of the 91 edited files was parsed and its description generated with the deployed generator:
tools/check_headings.pyis clean over the current versions, thetoolstests pass,update_eol.py --checkis clean, and no file is deleted.Not included
The five English-only duplicate pages in
en/15.7/config/(analyzer,role-setting,virtual-host,search-config,index-backup), which duplicate pages that exist in all seven languages and each canonicalise to themselves. The cannibalisation is real —search-configandsearch-advancedtogether drew 92 impressions and zero clicks — but the whole set is 276 impressions against the site's 187,000, so it is tidying rather than traffic, and merging or redirecting them is a decision worth making separately.