Skip to main content

Docusaurus v3.0.0

Today I learned to upgrade this site to Docusaurus v3.0.01 and there were some breaking changes that had to be fixed2,3.

The biggest changes are that version 3 requires React 18 and Typescript 5. The majority of breaking changes for me were related to the MDX4 upgrade from v1 to v3 and the subsequent markdown formatting. Indented code blocks, {brackets}, and <hyperlinks> were kicking errors which took a bit of manual labor to clean up.

The Prism React Renderer was also upgraded to v2 so I switched the highlighting over to the OneDark theme. I made notes in the site log5 and this is now the current list of packages for this site

david@ovid🏛 :~/sites/daw_til(main⚡) » npm list     
daw-til-2@0.0.1 /Users/david/Sites/daw_til
├── @docusaurus/core@3.0.0
├── @docusaurus/plugin-content-blog@3.0.0
├── @docusaurus/preset-classic@3.0.0
├── @docusaurus/theme-mermaid@3.0.0
├── @mdx-js/mdx@3.0.0
├── @mdx-js/react@3.0.0
├── clsx@2.0.0
├── docusaurus-lunr-search@3.3.0
├── docusaurus-plugin-matomo@0.0.6
├── markprompt@0.1.7
├── plugin-image-zoom@1.1.0 (git+ssh://git@github.com/flexanalytics/plugin-image-zoom.git#8e1b866c79ed6d42cefc4c52f851f1dfd1d0c7de)
├── react-dom@18.2.0
├── react-player@2.13.0
└── react@18.2.0

I use a couple add-ons: Lunr search, Matomo analytics, an image zoom, and MarkPrompt for Supabase indexing. I've customized a couple of things to make it visually blend into my primary domain. I originally started this site as just a set of local markdown and text files. I migrated it to gitbook when I started storing the files in a repo and publishing them. I migrated it to Docusaurus when gitbook stopped being supported as an open source project. Nowadays, I use it constantly because it's easy to keep my docs and notes updated, in sync, and online.

One of the biggest assets about keeping all of the copy (data) of these site in plain markdown files is that it's relatively easy to dump them into a vector database to use against an AI model as compared to having various flavored markup interspersed into the database of a more traditional CMS. The default Docusaurus front-end theme now handles async rendering and at some point I'll start integrating some other data sources into it and customize the AI model/vector embeddings to make it more useful for me.

tip

Big thanks 👏🏼 to Sébastien Lorber6 who does a lot of the work on Docusaurus.

  1. Announcing Docusaurus 3.0 - https://docusaurus.io/blog/releases/3.0
  2. Preparing your site for Docusaurus v3 - https://docusaurus.io/blog/preparing-your-site-for-docusaurus-v3
  3. Docusaurus v3.0.0 Breaking Changes - https://github.com/facebook/docusaurus/discussions/9312
  4. MDX - https://mdxjs.com
  5. TIL Help - til/help
  6. Sébastien Lorber - https://github.com/slorber