2.4.3 👉🏼 3.0.0

docusaurus.config.js

@@ -1,4 +1,7 @@
 /** @type {import('@docusaurus/types').DocusaurusConfig} */
+
+import {themes as prismThemes} from 'prism-react-renderer'
+
 module.exports = {
   title: 'David Windham | TIL',
   tagline: 'Because Today I Learned',
@@ -84,7 +87,8 @@ module.exports = {
       },
     },
     prism: {
-      additionalLanguages: ['php', 'rust', 'shell-session', 'swift', 'diff'],
+      theme: prismThemes.oneDark,
+      additionalLanguages: ['php', 'rust', 'bash', 'shell-session', 'swift', 'diff'],
     },
     colorMode: {
       defaultMode: 'dark',

posts/2023-11-12-posts.md

@@ -0,0 +1,61 @@
+---
+title: Docusaurus v3.0.0
+description: Today I learned to migrate docusaurus to v3.0.0
+slug: docusaurus-3
+<!--- authors:
+  - name: David Windham
+    title: Something Else
+    url: https://davidawindham.com
+    image_url: https://davidawindham.com/wp-content/themes/daw/img/opengraph_image.jpg -->
+tags: [software, web]
+image: https://davidawindham.com/wp-content/themes/daw/img/opengraph_image.jpg
+hide_table_of_contents: true
+---
+
+Today I learned to upgrade this site to Docusaurus v3.0.0<sub>1</sub> and there were some breaking changes that had to be fixed<sub>2</sub>. 
+
+<!--truncate-->
+
+The biggest changes are that version 3 requires React 18 and Typescript 5. The majority of breaking changes for me were related to the MDX<sub>3</sub> 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 log<sub>4</sub> and this is now the current list of packages for this site 👇🏼
+
+```js
+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 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 might consider integrating other data sources into it. 
+
+:::tip
+
+Big thanks 👏🏼 to Sébastien Lorber<sub>5</sub> who does 90+% of the work on it. 
+
+:::
+
+
+
+---
+
+1. Preparing your site for Docusaurus v3 - https://docusaurus.io/blog/preparing-your-site-for-docusaurus-v3
+2. Docusaurus v3.0.0 Breaking Changes - https://github.com/facebook/docusaurus/discussions/9312
+3. MDX - https://mdxjs.com
+4. TIL _Help_ - [til/help](/help)
+5. Sébastien Lorber - https://github.com/slorber

src/pages/help.md

@@ -41,7 +41,9 @@ gitGraph
 - https://github.com/windhamdavid/til
 
 ### Docusaurus
+
 [https://docusaurus.io/docs](https://docusaurus.io/docs)
+
 ```bash
 npm install
 npm run start
@@ -49,6 +51,8 @@ npm run build
 npm run serve
 ```
 
+#### v3.0.0
+
 **23/11/12** - Docusaurus updated 2.4.3 👉🏼 3.0.0 and React 17.0.2 👉🏼 18.2.0
 
 ```bash
@@ -67,26 +71,21 @@ react-dom                         17.0.2  17.0.2  18.2.0  node_modules/react-dom
 
 :::danger
 
-v3 now requires React 18 and Typescript 5
+Docusaurus v3 now requires React 18 and Typescript 5
 
 This introduced a bunch of breaking errors in the markdown formatting via the MDX formatting that are documented at:
 - [https://docusaurus.io/blog/preparing-your-site-for-docusaurus-v3](https://docusaurus.io/blog/preparing-your-site-for-docusaurus-v3)
 - [https://github.com/facebook/docusaurus/discussions/9312](https://github.com/facebook/docusaurus/discussions/9312). 
 
-Went in and cleaned up the markdown formatting - mostly the tags on links and indented code highlighting formatting.
-
 :::
 
-The build process was also failing due to some errors defining text wrapped in `{}` 👇🏼
+Went in and cleaned up the markdown formatting - mostly the tags on links and indented code highlighting formatting.The build process was also failing due to some errors defining text wrapped in `{}` 👇🏼
 
 ```bash
 Error: Failed to compile due to Webpack errors.
   Error: Docusaurus server-side rendering could not render static page with path /docs/editors/git because of error: stash_number is not defined
-
   Error: Docusaurus server-side rendering could not render static page with path /docs/lang/Rust because of error: url is not defined
-
   Error: Docusaurus server-side rendering could not render static page with path /docs/shell/zsh because of error: bz2 is not defined
-
   Error: Docusaurus server-side rendering could not render static page with path /lists/tweets_follow because of error: SoftwareHardwareDeveloperDesignerMakerInventor is not defined
       at /Users/david/Sites/daw_til/node_modules/@docusaurus/core/lib/webpack/utils.js:207:24
       at /Users/david/Sites/daw_til/node_modules/webpack/lib/MultiCompiler.js:554:14