Fix docs build - #500
Merged
Merged
Fix docs build#500
Conversation
`docs/src/.vitepress/config.mts` is committed, so DocumenterVitepress uses it instead of substituting its own template (the build log lists a substitution for every `.vitepress` file except `config.mts`). It was a fork of the 0.2 template, so the 0.3 bump left it out of step with the new `docs/package.json`: - it imported `markdown-it-mathjax3`, which 0.3 no longer installs, failing the vitepress build with `Cannot find package 'markdown-it-mathjax3'`; - 0.3 copies in its own `VersionPicker.vue`, which reads `__DEPLOY_ABSPATH__`, defined only by the `vite.define` block the 0.2 config lacks — so restoring the npm package alone would just have moved the failure one step later. Rebase it on the 0.3.5 template, keeping our four customizations (`ignoreDeadLinks`, the custom nav, the Slack social link and the footer copyright). The nav gains the `VersionPicker` entry, which is how 0.3 renders the version dropdown. `theme/index.ts` was an unmodified copy of the 0.2 template, so delete it and let DocumenterVitepress substitute the current one. That picks up `virtual:mathjax-styles.css` (where MathJax 4's SVG styling now comes from), `docstrings.css`/`overrides.css` and the sidebar drawer toggle, and future template changes now arrive with the package. Our `theme/style.css` is untouched and still overrides the defaults. `config.mts` cannot be dropped the same way: without `ignoreDeadLinks` the build fails on two dead `./@ref` links in `man/listfunctions.md`, left by the unresolved `accumulate_tensor!` references Documenter already warns about. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`accumulate_vol!`'s docstring links to [`accumulate_tensor!`](@ref), but `accumulate_tensor!` carried no docstring, so Documenter had no binding to resolve against and warned once per module. The unresolved reference was emitted as a literal `./@ref` link, which is what the two dead links vitepress reports on `man/listfunctions` are. Give it a docstring. The reference now resolves to the generated anchor and the dead links are gone. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`ignoreDeadLinks: true` was in the vendored config to tolerate the two `./@ref` links left by the unresolved `accumulate_tensor!` reference. That reference now resolves, and a full build passes with dead-link checking on, so drop the flag instead of leaving it to swallow future broken links silently. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
aelligp
approved these changes
Aug 3, 2026
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
2 participants
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.
Fixes the docs build on #499.
config.mts— our committed copy is a 0.2-era fork, so it still importedmarkdown-it-mathjax3, which 0.3 no longer installs. Rebased on the 0.3.5 template, keeping the custom nav, Slack link and footer copyright. Re-adding the npm package alone wouldn't have been enough: 0.3'sVersionPicker.vuereads__DEPLOY_ABSPATH__, which the 0.2 config never defines.theme/index.ts— no local changes, so deleted; DocumenterVitepress supplies the current one, bringing the MathJax 4 stylesheet, docstring CSS and sidebar toggle.theme/style.cssuntouched.accumulate_tensor!— documented, soaccumulate_vol!'s@refresolves instead of emitting the two./@refdead links onman/listfunctions.ignoreDeadLinks— no longer load-bearing, dropped.🤖 Generated with Claude Code