Docusaurus v3 - #28
Merged
Merged
Conversation
Bump @docusaurus/core and preset-classic from 2.0.0-alpha.66 to 3.10.2, React 16 to 18, and swap classnames for clsx. Node 20 is now the minimum, so pin 22 via .nvmrc and raise the CI runner. Config moves to the v3 shape: add i18n and markdown.hooks, relocate gtag from themeConfig to the preset, and set the site url to the domain the CNAME actually serves so canonical tags and the sitemap resolve correctly. Broken link and anchor handling is set to throw. Update docs for MDX v3, which parses .md as MDX and no longer tolerates HTML comments, bare braces, or class attributes on raw HTML. Replace hardcoded light colors in the stylesheets with Infima tokens that adapt to the active theme, and drop two theme classes that no longer exist in v3, one of which was hiding the color mode toggle. Add a tsconfig and type the viz components so npm run typecheck passes. Rename docs/readme.md, which v3 resolved as a folder index rather than a page, and remove the leftover GitBook config and table of contents.
The root img directory duplicated static/img, which is the one Docusaurus actually serves, and nothing referenced it. Every image path in the docs resolves from static/img. Regenerate package-lock.json under the Node version the project now targets so the lockfile format matches what CI installs with.
The deploy workflow only runs on master, so a change to the build could not be exercised before it published. Add a job that installs, typechecks and builds on pull requests without deploying. Both workflows now take the Node version from .nvmrc so local and CI cannot drift apart.
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.
This PR upgrades the docs site from Docusaurus 2.0.0-alpha.66 to 3.10.2. The old version was an alpha release, and the build only ran with a legacy OpenSSL flag that was set using Windows shell syntax. Summary of changes below:
Dependencies. Docusaurus 2 alpha to 3.10.2, React 16 to 18. Node 20 is the new minimum, so the version is pinned in
.nvmrcand both workflows read it from there.Docs content. Version 3 reads
.mdfiles with a stricter parser. A few pages used syntax it rejects, so those are updated: HTML comments in the two Docker pages, curly braces inreport.md, andclassattributes on plain HTML links.Site address. The config pointed at
flexit.github.io, but the site is served fromlearn.flexitanalytics.com. Every page was telling search engines the wrong home address and the sitemap listed the wrong host. Now corrected.Dark mode. Version 3 shows a light and dark toggle that version 2 was hiding. The stylesheet had fixed light colors that looked wrong against a dark background, so those now follow whichever mode is active. Affects blockquotes, image borders, heading rules, sidebar lines and the homepage hover state.
Search. Contextual search is switched off. Version 3 switches it on by default, and it filters on a field our index does not have, which made search return nothing at all.
Cleanup. Removed leftover GitBook files (
book.json,.bookignore,docs/SUMMARY.md). Removed the rootimgfolder, which duplicatedstatic/imgand was not referenced anywhere. Renameddocs/readme.md, which version 3 was treating as a folder index rather than a page, so links to it were broken.CI. Added a build check that runs on pull requests. The deploy workflow only runs on master, so until now a change to the build could not be tested before it published.
Verification
CNAMEstill lands in the build output, so the custom domain holds