Skip to content

docs: give the 63 pages that ship no meta description an opening sentence - #468

Merged
marevol merged 3 commits into
masterfrom
fix/seo-followup
Aug 8, 2026
Merged

docs: give the 63 pages that ship no meta description an opening sentence#468
marevol merged 3 commits into
masterfrom
fix/seo-followup

Conversation

@marevol

@marevol marevol commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

Sixty-three pages in the sitemap ship no meta description at 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:

impressions clicks CTR
all 63 1,810 71 3.9%
ja/15.7/install/index 689 27 3.9%
15.7/admin/index (English) 270 3 1.1%
ja/development 118 6 5.1%
tutorial (English) 73 1 1.4%

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.rst and archives.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.rst 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 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.rst and archives.rst wrap mid-sentence without the trailing backslash, so API、 各種設定 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:

  • 91/91 produce a non-empty description, none over 200 characters
  • no two different pages share a description
  • no unresolved substitution or leaked markup in any of them
  • no rendered paragraph contains a space between two CJK characters
  • each new overview title is unique within its language; the old title now belongs only to the settings page it describes

tools/check_headings.py is clean over the current versions, the tools tests pass, update_eol.py --check is 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-config and search-advanced together 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.

marevol added 3 commits August 8, 2026 17:36
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
marevol merged commit 25dd688 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