<img src={require('./img/docusaurus.png').default} alt="Upgrading Docusaurus" width="900" height="450" /> <br/> Maintaining documentation is a long-term commitment. As frameworks evolve, upgrades become inevitable to stay secure, supported, and compatible with modern tooling. This blog documents a real-world upgrade journey from **[Docusaurus](https://docusaurus.io/) 3.1.0 to [Docusaurus 3.9.2](https://github.com/facebook/docusaurus/releases)**, along with a **[Node.js](https://nodejs.org/) upgrade to version 20**, and the MDX and Markdown fixes required to get the project building successfully again. The goal of this guide is to help teams avoid common pitfalls and understand *why* certain issues appear during the upgrade. --- ## Why Upgrade Docusaurus and Node.js ### Docusaurus Upgrade Motivation Upgrading from Docusaurus 3.1.0 to 3.9.2 provides: - Improved MDX parsing and validation - Better ESM and Vite compatibility - Security fixes and dependency updates - More predictable theme and plugin behavior ### Node.js 20 Requirement Docusaurus 3.9.2 officially supports modern Node.js versions. Node.js 16 is deprecated, and Node.js 18 is approaching maintenance mode. Upgrading to **Node.js 20** ensures: - Long-term support - Faster builds - Better compatibility with modern tooling For teams deploying documentation alongside applications on **[Nife’s platform](https://nife.io/platform)**, aligning Node.js versions avoids runtime inconsistencies. --- ## Step 1: Upgrade Node.js to Version 20 Before touching Docusaurus, ensure Node.js is upgraded. Using NVM: ```bash nvm install 20 nvm use 20 node -v ``` Verify npm as well: ```bash npm -v ``` Clean the environment: ```bash rm -rf node_modules package-lock.json npm cache clean --force ``` --- ## Step 2: Upgrade Docusaurus to 3.9.2 Update all Docusaurus-related dependencies together to avoid version mismatches. ```bash npm install @docusaurus/core@3.9.2 \ @docusaurus/preset-classic@3.9.2 ``` If you are using additional plugins or themes, upgrade them to matching versions. After installation: ```bash npm install npm run build ``` At this stage, most projects will fail due to **MDX or theme-related issues**. --- ## Step 3: Common MDX and Markdown Breaking Changes ### 1. Stricter MDX Parsing Docusaurus 3.9.2 enforces stricter MDX rules. #### Common Issues - Unclosed JSX tags - Invalid HTML inside Markdown - Incorrect frontmatter formatting - Trailing commas in arrays #### Example Fix Incorrect: ```mdx <img src="./img/sample.png"> ``` Correct: ```mdx <img src="./img/sample.png" /> ``` --- ### 2. Frontmatter Validation Errors Ensure all frontmatter fields are valid YAML. Incorrect: ```mdx keywords: [docs, guide, ] ``` Correct: ```mdx keywords: [docs, guide] ``` --- ### 3. JSX Must Be Explicit in MDX Any JSX expression must be properly wrapped. Incorrect: ```mdx {someFunction()} ``` Correct: ```mdx {someFunction && someFunction()} ``` --- ## Step 4: Fixing Image Imports in MDX Docusaurus 3.x requires explicit image imports when using JSX. Recommended pattern: ```mdx <img src={require('./img/architecture.png').default} alt="Architecture Diagram" width="800" /> ``` Avoid relative Markdown image syntax for complex layouts. --- ## Step 5: Theme Component Errors After Upgrade One of the most common errors during upgrade: ```text Module not found: Error: Can't resolve '@theme/Hero' ``` ### Why This Happens - Docusaurus 3.9.2 removed or refactored internal theme components - Custom themes built for older versions are incompatible ### Resolution Strategy 1. Temporarily disable all custom theme components 2. Replace theme imports with standard MDX or React components 3. Gradually reintroduce custom components after validation Example removal: ```tsx // Remove this import Hero from '@theme/Hero'; ``` --- ## Step 6: Sidebar and Routing Validation Docusaurus 3.9.2 enforces stricter route validation. Ensure: - All sidebar paths exist - Slugs are unique - No duplicate document IDs Run: ```bash npm run clear npm run build ``` --- ## Step 7: Final Build and Verification Once MDX and theme issues are resolved: ```bash npm run build npm run serve ``` Verify: - All pages load correctly - Sidebar navigation works - Images render as expected - No console warnings or errors --- ## Key Takeaways - Always upgrade Node.js before upgrading Docusaurus - Expect MDX parsing to be stricter in newer versions - Custom themes are the most common breaking point - Clean installs prevent dependency conflicts - Incremental fixes are faster than mass refactors --- ## Conclusion Upgrading from **Docusaurus 3.1.0 to 3.9.2** with **Node.js 20** is not just a dependency bump. It is a validation of documentation quality, MDX correctness, and long-term maintainability**[Nife containerized deployments](https://nife.io/solutions/deploy_containarized_apps)**. By addressing MDX issues early and removing outdated theme dependencies, teams can ensure a smooth and future-proof documentation platform. This upgrade prepares your documentation for scalability, security, and continued evolution alongside your product**[Nife](https://nife.io)**.
