Conversation
|
After the build completes, the updated documentation will be available here |
Codecov Report❌ Patch coverage is
... and 4 files with indirect coverage changes 🚀 New features to boost your workflow:
|
|
This looks amazing! I certainly didn't go in detail through the preview, but something I already noticed is that the links to the examples inherit the reference label instead of the title if provided. |
|
I think the new look is okay, but I don't feel it's that much of an improvement compared to the default Documenter style. I much prefer the navigation and search tools of this update though, very smooth. However, I'm not really a fan of adding this much HTML/CSS to the repo. I know this wasn't manually generated, but there's still a lot of properties being manually specified, and I have no idea how any of this works. Do we really need to add this much CSS, or is there a more standard template that we can reuse that would lead to less CSS in the repo itself while still being reliable? |
|
Fair point, let me investigate that a bit more. I think quite a lot of it is just that I asked for a custom theme that goes along with the MPSKit colors, so probably it's just a matter of getting rid of the theme and using a bit more defaults. That being said, I do really like the landing page a lot more, so this is probably the only thing I will try to keep, either through some template or just by manually keeping this in. In general this is stuff that doesn't really need to be touched so I think a little of it is fine, but I do agree that it is better not to overengineer this for maintainability purposes |
|
Your PR no longer requires formatting changes. Thank you for your contribution! |
lkdvos
force-pushed
the
ld-docs
branch
2 times, most recently
from
a522f00 to
67448f7
Compare
|
I think I managed to remove a bunch of the css, and did some other improvements on the entire system - for example improving load times by not inlining the images. I think it looks a lot better now, and would be happy to merge as-is. |
Switch the documentation backend from `Documenter.HTML` to `DocumenterVitepress.MarkdownVitepress` for a modernized look: a hero landing page, cleaner navigation, built-in dark mode and local search. - Add `DocumenterVitepress` to the docs project and bump `Documenter` to 1.11. - Swap `format`/`deploydocs` to the VitePress equivalents in `make.jl` and drop the MathJax3 block (the bundled MathJax already loads the `braket` package, covering the `\ket`/`\bra` macros used). - Generate the `.vitepress` config/theme/components and `package.json`. - Convert `index.md` into a VitePress hero landing page with a feature grid. - Port the `.color-invertible` image dark-mode inversion and a green logo accent into the theme stylesheet; remove the obsolete `assets/custom.css`. - Fix `<img>` relative paths for VitePress's build-time resolution (`./file`, `../assets/...`); the old paths assumed Documenter's prettyurls directory depth. - Add a favicon rendered from the logo. Node is bundled via `NodeJS_20_jll`, so no CI workflow change is needed. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The VitePress hero frontmatter was written as a bare `---...---` block at the top of `index.md`, which Documenter consumed as its own page metadata instead of forwarding to VitePress. As a result `layout: home` never took effect and the hero fields rendered as plain body text with no VPHero. Wrap the frontmatter in a ```@raw html``` block (the DocumenterVitePress idiom) so Documenter emits it verbatim to the top of the output markdown, where VitePress parses it as real frontmatter. Also add emoji icons to the feature cards. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The `@contents` block rendered manual-page headings of the form `# [Title](@id anchor)` as the bare anchor id (`um_states`, `um_operators`, …) under DocumenterVitepress instead of the title text. Replace it with an explicit `@ref` link list so the ToC shows real section titles, and drop the dead `man/conventions.md` entry (no such file exists). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The @contents blocks in examples/index.md rendered example-page headings of the form `# [Title](@id anchor)` as the bare anchor id (demo_haldane, hubbard, …) under DocumenterVitepress. These anchors were unreferenced anywhere, so drop the `[…](@id …)` wrapper and use plain `# Title` headings, which @contents renders correctly while keeping the readdir-based auto-discovery of examples. Fixed in both the generated index.md and the Literate main.jl sources so it survives regeneration. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Plots.jl figures were baked into the generated example index.md as base64 inside `@raw html`/`<img data:image/png;base64,…>` blocks, bloating the committed pages (xy-finiteT 323 KB, bose-hubbard 204 KB, …; ~1.2 MB total). Add a centralized `externalize_figures` (examples/figure_externalization.jl): it decodes those base64 blocks to external `figure-N.png` files next to the page and rewrites them to standard markdown ``, keying only on `data:…;base64,` so file-referenced SVG diagrams are left untouched. Wire it as the Literate `postprocess` in examples/make.jl so future regenerations stay externalized, and apply it once to the already-committed pages (decoding the existing figures verbatim — no example re-execution). 27 figures externalized across 8 pages; VitePress bundles them via /assets. Full docs build stays green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The DocumenterVitepress cutover vendored 10 files under docs/src/.vitepress and docs/src/components; 9 were byte-identical to the DVP template, which the backend re-supplies into the build automatically when they are absent. Delete those 9 boilerplate files and move the only genuine customizations (MPSKit-green light-mode branding and the .color-invertible dark-mode diagram inversion) into a small theme/custom.css imported from theme/index.ts. The rendered site is unchanged; the repo now carries ~2 small files instead of ~10. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
DocumenterInterLinks only expands @extref when it is the destination of an inline markdown link, `[text](@extref target)`. Four docstrings used reference-style `[text][@extref ...]` or a mismatched `(@extref ...]`, so they rendered as literal text instead of external links. Fix the truncation links in RandExpand, SvdCut and VUMPSSvdCut, and the Arnoldi link in ChepigaAnsatz. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
I'm rerunning the examples, and will then push this |
3 participants
Summary
Switches the documentation rendering pipeline from the default
Documenter.HTMLbackend toDocumenterVitePress.jl, giving the docs a modernized look: a hero landing page, cleaner navigation, built-in dark mode, and local search.Changes
make.jlnow usesDocumenterVitepress.MarkdownVitepressandDocumenterVitepress.deploydocs; theMathJax3block is dropped (VitePress's bundled MathJax already loads thebraketpackage, covering the only macros used,\ket/\bra).DocumenterVitepresstodocs/Project.tomland bumpedDocumentercompat to1.11.DocumenterCitations(bibliography) andDocumenterInterLinkscontinue to work unchanged..vitepressconfig/theme/components andpackage.json; ported the.color-invertiblediagram dark-mode inversion and a green logo accent into the theme stylesheet; removed the obsoleteassets/custom.css.index.mdis now a VitePress hero landing page with a feature grid.docs/src/assets/favicon.icorendered from the logo.<img>relative paths (./file,../assets/...) for VitePress's build-time asset resolution; the old paths assumed Documenter's prettyurls directory depth. Also fixed the Literate sourceexamples/quantum1d/1.ising-cft/main.jlso the fix survives regeneration.Scope
Backend cutover only. The diff is config/build/theme plus the content edits the backend requires (the hero landing page and the
<img>path fixes). The planned four-section Diátaxis restructure is intentionally not part of this PR —pages/nav still mirror the existing manual.CI
No workflow change needed — DocumenterVitePress bundles Node via
NodeJS_20_jll, and thepreviews/PR<n>deploy path is unchanged, so the existingDocumentation,PR_comment, andDocumentationCleanupworkflows keep working.Verification
A clean local
julia --project=docs docs/make.jlbuilds end-to-end: Documenter doctests + example execution +@autodocspass, then the VitePress build completes (~11s). Verified in the rendered output: hero page, logo, dark-mode-invertible diagrams, and bundled example images all render correctly.Re-verified locally on 2026-06-30:
make.jlbuilds end-to-end (doctests pass via the preservedsetdocmeta!, VitePressbuild complete in 11.89s), producingdocs/build/with 22 rendered HTML pages (index.htmltitled "MPSKit.jl", plusman/,lib/,examples/,changelog,references). No errors; the only warnings are pre-existing DocumenterCitations "could not link DOI" notes on a few bibliography entries.Deploy readiness (checked against the live repo)
Most deploy infrastructure is already in place from the prior Documenter HTML deploys:
DOCUMENTER_KEYsecret + deploy key — already configured (secret since 2020; thedocumenterdeploy key has write access). TheDocumentation.ymlbuild job already passesGITHUB_TOKEN+DOCUMENTER_KEY. No action.Deploy from a branch → gh-pages / (root)(build_type: legacy). No action.gh-pageslegacy symlinks —stableand thevX.Yaliases (v0.1…v0.13) are symlinks from the old Documenter layout. DocumenterVitepress cannot overwrite symlinked folders, so a future tagged-release deploy that updatesstable/vX.Ymay fail. Clean these up ongh-pagesbefore the first tagged deploy. Thedevdeploy from this branch writes to the realdev/directory and is unaffected.Left as a draft pending review; do not merge until the physics/content owners have looked it over.
🤖 Generated with Claude Code