Post

Preserving Reader Links and Section Anchors in OpenWiki Viewer

Preserving Reader Links and Section Anchors in OpenWiki Viewer

This push fixes how the OpenWiki viewer resolves internal links by replacing the old normalize function in client-lib.js with a new readerLink function that preserves explicit reader links and section anchors. The change ships as a standalone patch file and is applied automatically during site export, so readers following in-page markdown links stay on valid page targets instead of losing fragment context.

The new file scripts/openwiki-viewer-navigation.patch modifies client-lib.js by removing normalize(baseDir, rel) and adding readerLink(page, href). The replacement preserves explicit external links and host-root paths, resolves relative hrefs against a WIKI_FILES base path, detects wiki pages by their .md suffix, and returns either a resolved URL or a null value for non-wiki targets. Section anchors are retained because the URL resolution keeps the fragment portion of the href intact.

Export pipeline integration

The script scripts/export-openwiki-site.py now calls git apply --no-index --unidiff-zero -p0 against scripts/openwiki-viewer-navigation.patch inside the export output directory, applying the navigation change after the site is generated. The offline CI helper scripts/ci/offline-checks.sh gains one additional invocation of the export check test so the pipeline exercises the patched script during verification.

Verification and next steps

The commit is merged code, not a runtime deployment or observed test result, so the CI check has not yet been observed passing on this push. The next check is the offline CI pipeline run that invokes offline-checks.sh and confirms the patch applies cleanly without rejecting context. A platform team could reuse this technique by exporting generated documentation sites and applying a post-generation patch to fix client-side navigation before publishing.

This post is licensed under CC BY 4.0 by the author.