Skip to content

docs: give Japanese headings linkable anchors - #302

Merged
Naruto merged 1 commit into
developfrom
docs/unicode-heading-anchors
Sep 6, 2026
Merged

docs: give Japanese headings linkable anchors#302
Naruto merged 1 commit into
developfrom
docs/unicode-heading-anchors

Conversation

@Naruto

@Naruto Naruto commented Sep 6, 2026

Copy link
Copy Markdown
Collaborator

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.yml set no toc.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 _N id 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:

headings generic _N before → after ids moved
en 140 0 → 0 6
ja 140 70 → 0 130

The 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--visibility
  • Platforms & 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 (the Part Overrides link 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-featuresindex.md#主な機能-key-features
  • #web-gdextensionextensions-support-dlink#web-での-gdextensionextensions-support--dlink

The 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

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • This change requires a documentation update

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:

  • My code follows the style guidelines of this project
  • I have performed a self-review of my code
  • I have commented my code, particularly in hard-to-understand areas — the reason and the / caveat are in mkdocs.base.yml
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings — scripts/build-docs.sh (both locales, --strict) reports no issues
  • Any dependent changes have been merged and published in downstream modules — docs: generated assets, their dependencies, and getting them into a build #301 is merged

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.
@Naruto
Naruto merged commit 54af4a6 into develop Sep 6, 2026
0 of 2 checks passed
@Naruto
Naruto deleted the docs/unicode-heading-anchors branch September 6, 2026 07:45
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