fix(docs): bypass SPA routing for formula links to fix click→404#265
Merged
Conversation
Symptom: on /browse/, clicking a formula changed the URL to /browse/<slug>/ but the page showed 404. Refreshing loaded it correctly. Root cause: VitePress generates per-batch router manifests. Each CI build-batch job only includes ITS pages in the manifest. When you load /browse/ (from batch-N's app chunk) and click a link to a formula in batch-M (M!=N), Vue Router can't find the route in batch-N's manifest, immediately shows NotFound, and never even fetches the formula's chunk. This is a fundamental issue with multi-batch VitePress builds — not fixable without single-pass build (which OOMs on 4,283 pages). Fix: bypass SPA routing for formula navigation. Add @click.stop.prevent='goToFormula(slug)' to the formula links in FormulaBrowser.vue and index.md autocomplete. goToFormula() sets window.location.href, triggering a full page load. The server sends the correct HTML which loads the correct app chunk for that formula's batch. Same behavior as the user's manual 'refresh' workaround, just automatic. Preserves accessibility: <a href> is still set, so right-click 'open in new tab' and Ctrl+click work normally. SPA routing still works for all other internal links (guide, licenses, etc.). Only formula cross-batch navigation is affected.
Contributor
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
1 participant
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.
Problem
On
/browse/, clicking a formula changed the URL but the page showed 404. Refreshing loaded the page correctly. Same issue from any page with cross-batch formula links.Root cause
VitePress generates per-batch router manifests. Each
build-batchjob indocs.ymlruns its ownvitepress build, and the resulting app chunk (app.HASH.js) contains a route lookup table that ONLY includes that batch's pages.When you load
/browse/from batch-N's app chunk and click a formula that lives in batch-M (M ≠ N):Page not foundand renders NotFoundThis is why PR #264 (which deploys all batch assets) didn't fix the click 404 — the asset exists, but the router doesn't know the route exists.
Verified by downloading the deployed
app.BZgrPav2.js(from/browse/) and inspecting: it has 0 references tobrowse_andale.mdor any other batch-N's pages. The router manifest is per-batch by design.This is a fundamental limitation of multi-batch VitePress builds. The "proper" fix would be a single-pass build with all 4,283 pages, but that OOMs even with 6 GB heap + 8 GB swap (which is why the project went to multi-batch in the first place).
Fix
Bypass SPA routing for formula navigation. Add
@click.stop.prevent="goToFormula(slug)"to formula links in:docs/.vitepress/theme/FormulaBrowser.vue— the browse griddocs/index.md— the homepage autocomplete dropdowngoToFormula(slug)callswindow.location.href = ..., triggering a full page load. The server sends the correct HTML which references the correct app chunk for that formula's batch. The user sees the same behavior as their manual "refresh" workaround, just automatic.Preserved behavior
<a href>is still set — right-click "Open in new tab", Ctrl+click, and screen readers all work normallywindow.location.hrefdirectly, no change needed)Verification
After merge and deploy:
https://www.fontist.org/formulas/browse/https://www.fontist.org/formulas/