Skip to content

Conversation

dzienisz
Copy link
Member

@dzienisz dzienisz commented Sep 26, 2025

🚀 Upgrade Docusaurus to v3.9.1

Summary

This PR upgrades the Tolgee documentation site from Docusaurus 3.8.1 to 3.9.0, bringing performance improvements, new features, and important security updates.

📋 Changes Made

Core Package Updates

  • Docusaurus Core: Updated all @docusaurus/* packages from ^3.8.1 to ^3.9.1
    • @docusaurus/babel, @docusaurus/core, @docusaurus/mdx-loader
    • @docusaurus/plugin-content-docs, @docusaurus/preset-classic
    • @docusaurus/theme-classic, @docusaurus/theme-common, @docusaurus/utils
    • All development dependencies including @docusaurus/eslint-plugin, @docusaurus/module-type-aliases, etc.

Dependency Updates

  • @typescript-eslint/eslint-plugin: ^8.39.0^8.44.1
  • @typescript-eslint/parser: ^8.39.0^8.44.1
  • axios: ^1.8.1^1.12.2
  • posthog-js: ^1.165.0^1.268.5
  • tsx: ^4.19.3^4.20.6
  • clsx: ^1.1.1^2.1.1

Configuration Updates

  • Node.js Engine: Updated minimum requirement from >=18.0 to >=20.0 (required for Docusaurus 3.9)
  • Configuration Migration: Updated docusaurus.config.ts to use new markdown.hooks.onBrokenMarkdownLinks format instead of deprecated onBrokenMarkdownLinks

✨ New Features Available

🔍 Algolia DocSearch v4 with AskAI

  • Support for AI-powered search assistant that can answer questions based on documentation content
  • Opt-in feature - can be enabled by upgrading @docsearch/react and configuring themeConfig.algolia.askAi

🌐 Enhanced i18n Support

  • New i18n.localeConfigs[locale].{url,baseUrl} options for complex multi-domain deployments
  • Improved translation infrastructure with i18n.localeConfigs[locale].translate flag
  • Support for explicit translation keys in sidebar items to avoid conflicts

📊 Mermaid ELK Layout Support

  • Support for Eclipse Layout Kernel (ELK) algorithm for more sophisticated diagram layouts
  • Can be enabled by adding @mermaid-js/layout-elk dependency

🚀 Performance Improvements

  • Upgraded to Rspack 1.5 with new configuration options for faster builds
  • Optimized i18n infrastructure for non-i18n sites
  • Improved visual glitch handling in color mode switching

🔧 Technical Details

Breaking Changes

  • Node.js 18 Support Dropped: Minimum Node.js version is now 20.0 (Node.js 18 reached End-of-Life)
  • Configuration Migration: onBrokenMarkdownLinks moved to markdown.hooks.onBrokenMarkdownLinks

Compatibility

  • ✅ Current Node.js version (20.19.5) meets requirements
  • ✅ All existing configurations remain compatible
  • ✅ No breaking changes affecting current functionality

🧪 Testing

  • Build Test: npm run build completes successfully with no errors
  • Development Server: npm start runs correctly on localhost:3000
  • Dependencies: All packages installed without vulnerabilities
  • Configuration: New configuration format validated

📚 References

🎯 Impact

  • Performance: Faster builds with Rspack 1.5 optimizations
  • Security: Updated dependencies with latest security patches
  • Features: Access to new Docusaurus 3.9 features for future enhancements
  • Maintenance: Aligned with latest Docusaurus release for continued support

Note: This upgrade maintains full backward compatibility with existing content and configurations. The site will continue to function exactly as before, with improved performance and access to new optional features.

Copy link

netlify bot commented Sep 26, 2025

Deploy Preview for tolgee-docs ready!

Name Link
🔨 Latest commit dd9cf4d
🔍 Latest deploy log https://app.netlify.com/projects/tolgee-docs/deploys/68dd3ec60c790d00085d5944
😎 Deploy Preview https://deploy-preview-1014--tolgee-docs.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

@dzienisz dzienisz self-assigned this Sep 29, 2025
@dzienisz
Copy link
Member Author

@JanCizmar I don't have access to Algolia but from now we could activate DocSearch v4 with AskAI: https://docusaurus.io/blog/releases/3.9#docsearch-v4

@dzienisz dzienisz force-pushed the feat/docurusaurus-from-3.8-to-3.9 branch from 6354617 to 44893e8 Compare October 1, 2025 10:56
@dzienisz dzienisz changed the title chore: update Docusaurus to v3.9.0 and adjust dependencies versions chore: update Docusaurus to v3.9.1 and adjust dependencies versions Oct 1, 2025
@dzienisz
Copy link
Member Author

dzienisz commented Oct 1, 2025

@dkrizan can you confirm we use node 20 on our server?

@JanCizmar
Copy link
Contributor

Docusaurus is static side generator, so there is no Node on the server. Since it's built by Netlify, it will work.

@dzienisz
Copy link
Member Author

dzienisz commented Oct 1, 2025 via email

@dzienisz dzienisz force-pushed the feat/docurusaurus-from-3.8-to-3.9 branch from 44893e8 to dd9cf4d Compare October 1, 2025 14:46
@dzienisz
Copy link
Member Author

dzienisz commented Oct 3, 2025

@JanCizmar we can turn on Algolia DocSearch v4 with AskAI in future PR as it require much more work

@JanCizmar
Copy link
Contributor

That means that we can merge this?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants