The gonka-docs repository merged a small but build-critical fix on 2026-05-12 at 00:44 UTC. PR #1065 by @tcharchian corrects a script that broke docs CI after a navigation restructure landed seventeen minutes earlier. The change touches 11 added lines and 2 deletions in a single Python helper.

What changed

A separate PR (#1064) had reorganised the gonka-docs navigation into seven grouped sections: Learn, Developer, Host, Wallet & Tokens, Reference, and Resources. The Introduction page, previously a flat top-level entry, was moved into the new "Learn" section.

The site uses a helper called sync-docs-nav.py to rewrite the navigation before the static-site build runs. That helper has a transform_nav() function whose job is to remap Introduction: introduction.md to Introduction: index.md, because a separate stage script (prepare-stages.sh) deletes introduction.md from the build directory in favour of index.md.

The bug: transform_nav() only walked the top level of the navigation tree. After the restructure, Introduction sat one level deeper, inside Learn. The remap silently skipped it, the build looked for introduction.md, and CI failed with two warnings:

WARNING - A reference to 'introduction.md' is included in the 'nav'
configuration, which is not found in the documentation files.
WARNING - mkdocs_static_i18n: Could not find a homepage for locale 'en'/'zh'

PR #1065 makes transform_nav() recurse into nested lists, so the remap applies at any depth. The companion Home strip stays top-level-only by design. The PR author kept that part scoped to avoid changing unrelated behavior.

Why it matters

For readers of gonka.ai, the visible impact is nothing. The docs continued to build, since the broken version was caught in CI rather than shipped. For the docs CI itself, this removes a class of silent failure: any future nav restructure that moves a special-cased page like Introduction will keep working without a manual script edit.

The fix also reflects a discipline the gonka-docs team has been building around the strict build setting, where mkdocs warnings fail the build instead of being ignored. The change is small, eleven added lines, but it documents an awkward edge in the docs tooling. Special-case page remaps (Introduction to index, Home stripping) live in the build pipeline rather than in mkdocs.yml itself. As the navigation grows more nested, that pipeline needs to keep up.