docs: give Japanese headings linkable anchors - #302
Merged
Conversation
Python-Markdown's default slugify strips every non-ASCII character, so a heading with no Latin text in it slugified to nothing and the toc extension fell back to a positional id. Half the Japanese headings on this site -- 70 of 140 -- were `_1`, `_2`, `__1`, and so on. Those cannot be linked to on purpose, and they renumber whenever a heading is added above them, so a link that happened to work would rot silently. Writing a ja cross-reference meant naming the section in prose and letting the reader scroll. pymdownx.slugs.slugify keeps the text: `## 依存関係` is now `#依存関係`. No `_N` ids are left in either locale. The English ids stay put with one exception. pymdownx renders ` / ` and ` & ` as a double hyphen where the default collapsed them to one, which moves six ids here -- `part-overrides-color-cell-visibility` becomes `part-overrides-color--cell--visibility`. One link pointed into that set and is updated. Ten ja links pointed at ids that only existed because the Japanese had been stripped out of them (`#audio` for `サウンド (Audio)`, `#web-gdextensionextensions-support-dlink` for `Web での GDExtension(Extensions Support / dlink)`); those now name the section they meant. The three ja cross-references added with the generated-assets page go back to being anchors instead of prose. SpriteStudio-Docs, SSPlayerForUnity and SSPlayerForWgpu already carry this setting. SSPlayerForFlutter and SSPlayerForRenPy do not, and have the same unlinkable anchors.
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.
Description
Follow-up to #301, which had to write its Japanese cross-references in prose because a CJK anchor could not be linked.
mkdocs.base.ymlset notoc.slugify, so Python-Markdown's default was in force — and it strips every non-ASCII character. A heading with no Latin text in it slugified to nothing, and the toc extension fell back to a positional id. 70 of the 140 Japanese headings on this site were_1,_2,__1, … Those cannot be linked to on purpose, and they renumber whenever a heading is added above them, so a link that happened to work would rot silently.pymdownx.slugs.slugify(case=lower)keeps the text:## 依存関係is now#依存関係. After the change no_Nid is left in either locale.Blast radius
Measured by diffing the generated
<h2..h6 id=…>across a full build of both locales, before and after:_Nbefore → afterThe six English moves are the one behavioural difference worth knowing about: pymdownx renders
/and&as a double hyphen where the default collapsed them to one.Part Overrides (Color / Cell / Visibility)→part-overrides-color--cell--visibilityPlatforms & Export,Fastest Setup: Auto Node Creation via Drag & Drop,GDExtension on the Web (Extensions Support / dlink),Godot third-party build dependencies (AccessKit / ANGLE),A. Synchronizing with Events and Sound Effects (Call Method Track / Audio Track)Links fixed
Every internal anchor in
docs/was resolved against the new id set; 11 broke and all are updated in this commit. One is English (thePart Overrideslink from the troubleshooting page). The other ten are Japanese links that pointed at ids which only existed because the Japanese had been stripped out of them — they now name the section they actually meant:#audio→#サウンド-audio#routing-audio-elsewhere→#サウンドを別の基盤へ流す-routing-audio-elsewhere#spritestudio-sdk→#spritestudio-sdk-開発者向け#1-libssruntime→#1-libssruntime-の用意index.md#key-features→index.md#主な機能-key-features#web-gdextensionextensions-support-dlink→#web-での-gdextensionextensions-support--dlinkThe three ja cross-references added in #301 go back to being anchors instead of prose.
Family consistency
SpriteStudio-Docs, SSPlayerForUnity and SSPlayerForWgpu already carry this setting — this brings Godot in line. SSPlayerForFlutter and SSPlayerForRenPy still do not, and have the same unlinkable anchors; not touched here, happy to do them next.
Type of change
Existing deep links into the six moved English anchors from outside this repo, if any exist, would need updating. Within the repo everything is fixed.
Checklist:
/caveat are inmkdocs.base.ymlscripts/build-docs.sh(both locales,--strict) reports no issues