You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[Doc] Migrate the documentation to DocumenterVitepress #311
Agents: read the guide for agents in #310 first (order, difficulty, how to claim an issue, working method). The specification is in this description and in the comments below.
Goal
Move the documentation from Documenter's classic HTML backend to DocumenterVitepress, the current standard of the ecosystem (as in CTBase.jl, CTModels.jl, …), and bring the site in line with the SITE rules of ct-conventions.
Migration recipe: recipes/vitepress-migration.md in ct-agents.
Examples: docs/ of CTBase.jl and CTModels.jl (DocumenterVitepress 0.3.5, docs/package.json, docs/src/components/).
Points specific to this package
Generated pages: docs/problems.jl (one page per problem) and docs/browser.jl (interactive problems browser, raw HTML/CSS/JS) must work under VitePress. The browser is the main risk: raw HTML and scripts behave differently, a Vue component (as in docs/src/components/ of CTBase) may be needed.
Plots rendered as SVG (SITE12); they appear in every problem page.
Downloadable assets: make.jl copies Manifest.toml and Project.toml to docs/src/assets/. VitePress silently drops such files from the build: serve them from docs/src/public/ as well (see the notes on the VitePress backend in rules/site.md).
Mermaid: the site uses DocumenterMermaid; check how diagrams render under VitePress.
API reference generated with with_api_reference (SITE1, SITE2, SITE10), extensions documented when present (SITE3), InterLinks with local fallback inventories (SITE4).
Deployment on stable tags only, previews on request (SITE13): this changes .github/workflows/Documentation.yml. Pin the npm dependencies (SITE14).
Order
After the port to v2 (#283), which keeps the current pages building: a mechanical migration of the existing content to DocumenterVitepress, without rewriting it. The rewrite (#307) then happens directly in the VitePress structure, and the results pipeline and gallery (#314) in parallel. If the browser turns out hard to port, migrate it in its own PR, or leave it to #314 (gallery).
Addition: the gallery of problems of #314 (Vue component, filters, cards with SVG thumbnails) and the results copied into docs/src/public/results/ are part of the VitePress site; plan them in the migration.
From #304 (PRs #319, #324):test/README.md now documents the tests (layout, how to run, statuses and reports, labels, how to add a test or an environment), procedures only. The docs can link to it rather than duplicate it. In docs/make.jl, apply SITE18 (push LOAD_PATH, never pushfirst!), as the CTX packages now do.
The VitePress migration is in progress. The legacy interactive problems browser currently contains inline HTML/JavaScript that VitePress treats as Vue template and rejects during the build. Following the issue specification, I am deferring the browser to #314 (gallery) for a dedicated Vue/component migration; the VitePress site now documents this deferral and builds without the browser page.
Update: after discussing the direction, the browser is not being deferred to #314. The legacy inline HTML/DataTables implementation has been replaced in PR #382 by a new Vue component with native search, sorting, filters, constraint chips, row details, and CSV export. The old browser implementation is removed rather than carried forward.
Build with DocumenterVitepress.MarkdownVitepress; the generated problem pages (docs/problems.jl) work under VitePress.
The problems browser is a new Vue component (docs/src/components/ProblemsBrowser.vue: search, sorting, filters, constraint chips, row details, CSV export). It reads JSON generated by docs/browser.jl; the old HTML/DataTables code is removed.
Manifest.toml and Project.toml are also copied to docs/src/public/assets/, so VitePress serves them.
Deployment (SITE13): stable tags and main (dev), deploydocs guarded by bases.txt, previews on documentation push preview, DocPreviewCleanup.yml present.
npm versions pinned (SITE14).
Mermaid: the site has no diagrams, so nothing to check.
Activity
ocots commentedon Nov 4, 2026
Addition: the gallery of problems of #314 (Vue component, filters, cards with SVG thumbnails) and the results copied into
docs/src/public/results/are part of the VitePress site; plan them in the migration.ocots commentedon Nov 5, 2026
From #304 (PRs #319, #324):
test/README.mdnow documents the tests (layout, how to run, statuses and reports, labels, how to add a test or an environment), procedures only. The docs can link to it rather than duplicate it. Indocs/make.jl, applySITE18(pushLOAD_PATH, neverpushfirst!), as the CTX packages now do.ocots commentedon Nov 5, 2026
Taken by an agent; draft PR to follow.
ocots commentedon Nov 5, 2026
The VitePress migration is in progress. The legacy interactive problems browser currently contains inline HTML/JavaScript that VitePress treats as Vue template and rejects during the build. Following the issue specification, I am deferring the browser to #314 (gallery) for a dedicated Vue/component migration; the VitePress site now documents this deferral and builds without the browser page.
ocots commentedon Nov 5, 2026
Update: after discussing the direction, the browser is not being deferred to #314. The legacy inline HTML/DataTables implementation has been replaced in PR #382 by a new Vue component with native search, sorting, filters, constraint chips, row details, and CSV export. The old browser implementation is removed rather than carried forward.
ocots commentedon Nov 7, 2026
Written by Claude (Claude Code) at the request of ocots.
Closing: the migration is done by #382
Checked against
main(c3ade68) and theSITErules of ct-conventions v0.10.0.Delivered by PR #382:
DocumenterVitepress.MarkdownVitepress; the generated problem pages (docs/problems.jl) work under VitePress.docs/src/components/ProblemsBrowser.vue: search, sorting, filters, constraint chips, row details, CSV export). It reads JSON generated bydocs/browser.jl; the old HTML/DataTables code is removed.Manifest.tomlandProject.tomlare also copied todocs/src/public/assets/, so VitePress serves them.SITE13): stable tags andmain(dev),deploydocsguarded bybases.txt, previews ondocumentation push preview,DocPreviewCleanup.ymlpresent.SITE14).Moved elsewhere:
SITE12) and the localInterLinksinventories (SITE4): [Doc] Finish the VitePress migration: plots as SVG and local InterLinks inventories #407.with_api_referenceand the extensions documented (SITE1,SITE2,SITE3,SITE10): in the rewrite [Doc] Rewrite the documentation: getting started, user guide, problems, developers #307, which already plans it.#307 and #314 no longer wait for this issue.