docs: vendor the VitePress config; serve static assets from public/ - #497
Draft
lkdvos wants to merge 1 commit into
Draft
docs: vendor the VitePress config; serve static assets from public/#497lkdvos wants to merge 1 commit into
lkdvos wants to merge 1 commit into
Conversation
This was
linked to
issues
Aug 3, 2026
Contributor
|
After the build completes, the updated documentation will be available here |
Codecov Report✅ All modified and coverable lines are covered by tests. 🚀 New features to boost your workflow:
|
`MarkdownVitepress` does not expose `themeConfig.search` or `markdown.config`, so `docs/src/.vitepress/config.mts` is vendored from the DocumenterVitepress template with the MPSKit-specific hooks added on top. Since a vendored copy silently rots, `make.jl` checksums the upstream template and warns when it changes, naming the two template versions our copy is known to be a faithful superset of. VitePress serves files under `src/public/` verbatim at the site root, which is what the logo and favicon need; `src/assets/` is for files Documenter itself processes. Move them accordingly and add the landing-page feature icons alongside. The new `theme/custom.css` also repairs the base font stack behind #477. VitePress self-hosts Inter as a variable font (`wght` axis 100–900, emitted into the site's own `assets/`) and names it first in `--vp-font-family-base`. The DocumenterVitepress template then overrides that variable with `"Barlow", "Inter var experimental", "Inter var", …`: Barlow is never loaded, the two `Inter var` names are what VitePress called the face before it moved to Inter v4 (vuejs/vitepress#3694), and plain `"Inter"` is absent — so the bundled font went unused and text fell through to a platform substitute, which on Linux exposed no real bold face. Restoring VitePress' own stack verbatim gets real 600/700 faces back, with no webfont to add and nothing fetched from a third party. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
lkdvos
force-pushed
the
docs/vitepress-config
branch
from
August 4, 2026 13:17
ba71529 to
a924fd7
Compare
Member
|
Docstring headers look bold to me now, and I can target library entries with the search like I wanted! |
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
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.
Split out of #449 so it can be reviewed on its own; independent of the documentation content.
MarkdownVitepressdoes not exposethemeConfig.searchormarkdown.config, sodocs/src/.vitepress/config.mtsis vendored from the DocumenterVitepress template with the MPSKit hooks added on top. Since a vendored copy silently rots,make.jlchecksums the upstream template and warns when it changes, naming the versions our copy is a faithful superset of.VitePress serves
src/public/verbatim at the site root, which is what the logo and favicon need;src/assets/is for files Documenter processes. Moved accordingly.What this does about #477 and #478
Two independent things were going wrong.
Structure was invisible in docstrings. Documenter rewrites markdown headings inside a docstring into bold-only paragraphs (
recursive_heading_to_bold!), so there is no<h*>left to style. A markdown-it rule inconfig.mtstags exactly those paragraphs and the CSS gives them a heading-like treatment — spacing, size, and a light rule beneath — so the structure reads even where bold does not.Bold did not render as bold on Linux. VitePress' reset sets
font-synthesis: style, permitting a synthesised oblique but not a synthesised weight. That is fine wherever the resolved font has a real bold face, as-apple-systemandSegoe UIdo. But the DocumenterVitepress stack names three families it never loads (Barlow,Inter var experimental,Inter var), and on Linux fontconfig satisfies those and the platform names after them with a single regular face — every one of the 15 names in that stack resolves toDejaVuSans.ttf"Book" here. Sofont-weight: 700computes correctly and still paints at regular weight.This PR allows weight synthesis and does not touch the font stack, so nothing changes on platforms that already resolve a real bold face. It is deliberately the smallest change that fixes the reported symptom, and it is what I intend to propose upstream — at which point this rule can be deleted.
There is a deeper issue behind it, kept separate on purpose: VitePress self-hosts Inter with a real 100–900 weight axis, but the DocumenterVitepress stack names the family names VitePress used before vuejs/vitepress#3694 renamed the face to plain
Inter, and omits plainInter. Every DocumenterVitepress site therefore downloads a font it never uses. Naming it would give real bold faces rather than synthesised ones, but would also change body text on every platform — a look-and-feel decision for upstream, not something to fold into a bug fix.Unverified
The VitePress build cannot run on my machine (rollup's native module needs a newer glibc), so I have not seen this rendered. The mechanism checks out at every layer I could inspect, but confirmation that bold now reads as bold on Linux needs CI or a preview deploy — ideally from @leburgel, who reported #477 on Ubuntu/Mint.
🤖 Generated with Claude Code