Repository navigation
docs: migrate the website from Docusaurus to Fumadocs - #193
Merged
Merged
Conversation
|
Coverage after merging docs/fumadocs into main will be
Coverage Report
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Coverage after merging docs/fumadocs into main will be
Coverage Report
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Coverage after merging docs/fumadocs into main will be
Coverage Report
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
This was referenced Oct 8, 2026
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
1 participant
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.
Summary
This migrates the website, mutative.js.org, from Docusaurus 3.3 to Fumadocs 16.16 on Next.js 16.3, React 19.3 and Tailwind CSS 4.3, exported as a static site for GitHub Pages as before. The docs content is moved with
git mv, so its history follows the files, and its wording is unchanged apart from the conversions below. Every URL of the current site keeps working, including the ones that the library's production errors and development warnings print; only the template's example page,/markdown-page, is gone.Changes
zh-CNlocale was disabled and held the Docusaurus tutorial, and/markdown-pagewas the template's example.trailingSlash, the docs inwebsite/content/docsas MDX, the page H1 in thetitlefrontmatter,meta.jsonfiles for the sidebar order and labels thatsidebar_positionand_category_.jsongave, the static files inpublic, and a nested oxlint config so that the rootpnpm lintchecks the website with Next.js rules.#ff8800,#fb931fin dark mode) of the Docusaurus theme to the Fumadocs colors.:::tip,:::warningand:::cautionadmonitions to<Callout>.npm2yarncode blocks intonpmblocks, which show npm, pnpm, Yarn and Bun commands and remember the choice across pages.descriptionby their first paragraph, as Docusaurus did; 29 of the 30 meta descriptions are identical, and the TypeScript page now keepsDraft<T>, which Docusaurus dropped as HTML./blog/rss.xmland/blog/atom.xmlwith the same item ids, so feed readers keep the posts they have seen, and their<link rel="alternate">on every page..jsonfile, so that GitHub Pages can serve it compressed: 789 kB, 152 kB with gzip./docs/category/*to the overview pages,/blog/archive/and/blog/tags/*to/blog/, and/docs/to/docs/intro/. Static exports cannot use Next.js redirects, so the build writes pages with ameta refresh, a canonical link and a script that keeps the hash.sitemap.xml, now with the last update of each page.llms.txt,llms-full.txtand the Markdown of each docs page, with buttons to copy it or open it in an AI assistant.onBrokenLinks: 'throw'did; the check reads the exported HTML, so it also covers the sidebar, the footer and the redirects.gh-pages:pnpm publish:docsstill builds the site and pushes it to thegh-pagesbranch over SSH, with the same commit message.mainthat change it.Home page
The home page is redesigned in ten commits, in both color modes and from 320 px wide:
URL compatibility
/docs/getting-started/performanceand/blog/releases/1.0. GitHub Pages redirects them to the trailing slash, as it did for the Docusaurus output./docs/api-reference/create#create-on-a-draft,/docs/api-reference/current,/docs/extra-topics/errorsand/docs/advanced-guides/pathes#sets-of-objects.website/static/img/ mutative.pngstays where it is: the READMEs of the published npm packages load the logo from that path onmain. Next.js copies thestaticdirectory into the export, so the site also serves it at/static/img/.Differences from the Docusaurus site
<author>must be an email address.titleas the H1; the heading was "Shared References Behavior".llms.txtand the Markdown of each page, which it did not have.Verification
pnpm buildinwebsitegenerates 42 static routes and 8 redirect pages without warnings and checks the links of all 48 HTML files; a broken page link and a broken anchor added to a page made it fail.--frozen-lockfile, builds and passes the rootpnpm lintin a fresh clone; the first commit, which still uses Docusaurus, builds with Docusaurus.gh-pages --no-pushproduced the expectedgh-pagestree, with.nojekyllandCNAMEand without.DS_Storefiles; nothing was pushed, and the site has not been deployed.pnpm lint,pnpm format --checkandpnpm type-checkpass; no library file changes.