Skip to content

docs: vendor the VitePress config; serve static assets from public/ - #497

Draft
lkdvos wants to merge 1 commit into
mainfrom
docs/vitepress-config
Draft

docs: vendor the VitePress config; serve static assets from public/#497
lkdvos wants to merge 1 commit into
mainfrom
docs/vitepress-config

Conversation

@lkdvos

@lkdvos lkdvos commented Aug 3, 2026

Copy link
Copy Markdown
Member

Split out of #449 so it can be reviewed on its own; independent of the documentation content.

MarkdownVitepress does not expose themeConfig.search or markdown.config, so docs/src/.vitepress/config.mts is vendored from the DocumenterVitepress template with the MPSKit hooks added on top. Since a vendored copy silently rots, make.jl checksums 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 in config.mts tags 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-system and Segoe UI do. 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 to DejaVuSans.ttf "Book" here. So font-weight: 700 computes 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 plain Inter. 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

@github-actions

github-actions Bot commented Aug 3, 2026

Copy link
Copy Markdown
Contributor

After the build completes, the updated documentation will be available here

@codecov

codecov Bot commented Aug 4, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

`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
lkdvos force-pushed the docs/vitepress-config branch from ba71529 to a924fd7 Compare August 4, 2026 13:17
@leburgel

leburgel commented Aug 4, 2026

Copy link
Copy Markdown
Member

Docstring headers look bold to me now, and I can target library entries with the search like I wanted!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Documentation search can't target html identifiers in the lib page Markdown titles in docstrings not rendering properly in published docs pages

2 participants