Update to Docusaurus 3.4 + dependencies (#29)

* Bump docusaurus + update all dependencies:

- docusaurus 3-alpha -> 3.4
- everything to latest, except:
- eslint to v8, e.g. @typescript-eslint/parser doesn't support v9 yet
- typescript ~5.4, because eslint v8 expects a version <5.5.0
- node >= 18 due to various dependencies dropping 16

Change prism-react-renderer import as necessary

* Add @docusaurus/types as dev dependency - used in docusaurus.config.js already

* Migration to husky v9

* Fix broken file (due to mdx3 being less lenient)

* Update all used github actions:

- due to warning from github to versions using node 20

* Change build pipeline to .NET 8

* Update pnpm to latest (9.4.0):

Note: the new setup action now fails if a different version is used in package.json vs workflows config

* workaround API build failing on 5 files:

- these files used {string}, which is now evaluated as an expression in mdx (https://mdxjs.com/docs/what-is-mdx/#expressions)
-> setup docusaurus to only use mdx on .mdx files, because api is generated as normal .md

The docusaurus CommonMark feature is experimental: https://docusaurus.io/docs/markdown-features#mdx-vs-commonmark
With following limitations:facebook/docusaurus#9092

For reference, failing files were:
- "/api/Dalamud.Interface.Utility/Structs/ImVectorWrapper`T`"
- "/api/Dalamud.Utility.Timing/Classes/Timings"
- "/api/Dalamud.Utility/Classes/DisposeSafety.ScopedFinalizer"
- "/api/FFXIVClientStructs.Interop/"
- "/api/FFXIVClientStructs.Interop/Structs/SpanExtensions.SpanPointerEnumerator`T`"

* Add 'bash' as additionalLanguage for prisms syntax highlighting:

shell code wasn't highlighted, e.g. building/index.md

* Update README:

- Docusaurus 3 - always has been
- with v3 pnpm build works locally when using --dev

* Replace caution with warning due to deprecation in v3

* Change docusaurus.config.js to ES Module as recommended in the Migration Guide

.github/workflows/docs.yml

@@ -27,41 +27,41 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Setup pnpm
-        uses: pnpm/action-setup@v2
+        uses: pnpm/action-setup@v4
         with:
-          version: 8
+          version: 9.4.0
           run_install: false
       - name: Setup Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: 20
           cache: pnpm
       - name: Setup .NET
-        uses: actions/setup-dotnet@v3
+        uses: actions/setup-dotnet@v4
         with:
           dotnet-version: | # 6.0 required by dfmg
             8.0.x
-            6.0.x 
+            6.0.x
       - name: Install .NET tools
         run: |
           dotnet tool install -g docfx
           dotnet tool install -g DocFxMarkdownGen
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
       - name: Setup Docusaurus cache
-        uses: docuactions/cache@v1
+        uses: docuactions/cache@v1.1
       - name: Build
         run: pnpm run ci
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
       - name: Setup Pages
-        uses: actions/configure-pages@v3
+        uses: actions/configure-pages@v5
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v1
+        uses: actions/upload-pages-artifact@v3
         with:
           path: build/
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v2
+        uses: actions/deploy-pages@v4

.github/workflows/lint.yml

@@ -11,14 +11,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
       - name: Setup pnpm
-        uses: pnpm/action-setup@v2
+        uses: pnpm/action-setup@v4
         with:
-          version: 8
+          version: 9.4.0
           run_install: false
       - name: Setup Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: 20
           cache: pnpm

.husky/pre-commit

@@ -1,4 +1 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-
 pnpm lint-staged

README.md

@@ -1,6 +1,6 @@
 # Dalamud Documentation
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern
+This website is built using [Docusaurus 3](https://docusaurus.io/), a modern
 static website generator.
 
 ## Installation
@@ -30,7 +30,7 @@ docker compose up
 ## Build
 
 ```shell
-pnpm build
+pnpm build --dev
 ```
 
 This command generates static content into the `build` directory and can be

docs/building/index.md

@@ -120,7 +120,7 @@ injector with the following arguments:
 .\Dalamud.Injector.exe launch -f
 ```
 
-:::caution
+:::warning
 
 If your game is installed in a non-standard location, you must use the `-g`
 argument to pass the full path to `ffxiv_dx11.exe`, e.g.:

docusaurus.config.js

@@ -1,13 +1,13 @@
 // @ts-check
 // Note: type annotations allow type checking and IDEs autocompletion
-
-const lightCodeTheme = require('prism-react-renderer/themes/github');
-const darkCodeTheme = require('prism-react-renderer/themes/dracula');
+import { themes } from 'prism-react-renderer';
+const lightCodeTheme = themes.github;
+const darkCodeTheme = themes.dracula;
 
 const isDev = process.env.NODE_ENV === 'development';
 
 /** @type {import('@docusaurus/types').Config} */
-const config = {
+export default {
   title: 'Dalamud',
   tagline:
     'Documentation for the Dalamud plugin framework for FINAL FANTASY XIV.',
@@ -24,6 +24,12 @@ const config = {
   onBrokenLinks: 'ignore',
   onBrokenMarkdownLinks: 'warn',
 
+  // Some API comments contain curly brackets \{expression\} which are in the new mdx evaluated as expressions
+  // 'detect' uses mdx for .mdx files and CommonMark
+  markdown: {
+    format: 'detect',
+  },
+
   webpack: {
     jsLoader: (isServer) => ({
       loader: require.resolve('swc-loader'),
@@ -159,7 +165,7 @@ const config = {
       prism: {
         theme: lightCodeTheme,
         darkTheme: darkCodeTheme,
-        additionalLanguages: ['csharp'],
+        additionalLanguages: ['csharp', 'bash'],
       },
       colorMode: {
         defaultMode: 'dark',
@@ -173,5 +179,3 @@ const config = {
       },
     },
 };
-
-module.exports = config;

news/2023-09-21-dalamud-v9-stabilization.md

@@ -20,7 +20,7 @@ Please [check the full list of changes here](https://dalamud.dev/versions/v9/).
 
 One major change that you will encounter is that all of the services you've
 already been using are now accessed via interfaces, and not directly via the
-implementing type. <br> We decided to go this route, as it gives us the
+implementing type. <br/> We decided to go this route, as it gives us the
 opportunity to slowly switch all services over to plugin-specific services -
 which know what resources are allocated to what plugin, and allows us to track
 and dispose of them in case something goes wrong - and can enhance some Dalamud
@@ -36,11 +36,11 @@ services you're using with I. That's it!
 ### A note about ImGui
 
 I want to encourage everyone to have a look at the wonderful new ImRaii APIs we
-introduced into the main Dalamud assembly via `Dalamud.Interface.Utility`! <br>
+introduced into the main Dalamud assembly via `Dalamud.Interface.Utility`! <br/>
 They make it a lot easier to prevent crashes your plugin may cause due to e.g.
 unhandled exceptions, and are just all-around more convenient to use, in my
 opinion. You also will never again forget to pop a color, or that children
-always need to be ended. <br> There also are some other convenience APIs, for
+always need to be ended. <br/> There also are some other convenience APIs, for
 example, to interact with tables.
 
 Another thing you might want to look into, if you aren't already, is the Dalamud
@@ -70,4 +70,4 @@ not working correctly, please reach out to us via
 [#dalamud-dev](https://discord.com/channels/581875019861328007/860813266468732938)
 channel on our Discord server.
 
-Thanks for sticking around, and have a great autumn! <br> ~goat
+Thanks for sticking around, and have a great autumn! <br/> ~goat

package.json

@@ -2,7 +2,7 @@
   "name": "dalamud-docs",
   "version": "0.0.0",
   "private": true,
-  "packageManager": "pnpm@8.6.2",
+  "packageManager": "pnpm@9.4.0",
   "scripts": {
     "preinstall": "npx only-allow pnpm",
     "docusaurus": "docusaurus",
@@ -16,47 +16,48 @@
     "write-heading-ids": "docusaurus write-heading-ids",
     "typecheck": "tsc",
     "ci": "node ./ci-build.mjs",
-    "prepare": "husky install",
+    "prepare": "husky",
     "lint": "eslint . --ext js,jsx,ts,tsx,md,mdx --fix",
     "lint-ci": "eslint . --ext js,jsx,ts,tsx,md,mdx",
     "lint-staged": "lint-staged"
   },
   "dependencies": {
-    "@docusaurus/core": "3.0.0-alpha.0",
-    "@docusaurus/preset-classic": "3.0.0-alpha.0",
-    "@mdx-js/react": "^2.3.0",
-    "clsx": "^1.2.1",
-    "prism-react-renderer": "^1.3.5",
-    "react": "^18.0.0",
-    "react-dom": "^18.0.0"
+    "@docusaurus/core": "^3.4.0",
+    "@docusaurus/preset-classic": "^3.4.0",
+    "@mdx-js/react": "^3.0.1",
+    "clsx": "^2.1.1",
+    "prism-react-renderer": "^2.3.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.0.0-alpha.0",
-    "@docusaurus/tsconfig": "3.0.0-alpha.0",
-    "@octokit/rest": "^19.0.13",
-    "@swc/core": "^1.3.64",
-    "@typescript-eslint/eslint-plugin": "^5.60.0",
-    "@typescript-eslint/parser": "^5.60.0",
-    "eslint": "^8.43.0",
-    "eslint-config-prettier": "^8.8.0",
-    "eslint-plugin-mdx": "^2.1.0",
-    "eslint-plugin-prettier": "^4.2.1",
-    "husky": "^8.0.0",
-    "lint-staged": "^13.2.2",
-    "prettier": "2.8.8",
-    "remark-cli": "^11.0.0",
-    "remark-frontmatter": "^4.0.1",
-    "remark-gfm": "^3.0.1",
-    "remark-lint": "^9.1.2",
-    "remark-lint-final-definition": "^3.1.2",
-    "remark-lint-maximum-heading-length": "^3.1.2",
-    "remark-lint-no-file-name-mixed-case": "^2.1.2",
-    "remark-preset-lint-consistent": "^5.1.2",
-    "remark-preset-lint-markdown-style-guide": "^5.1.3",
-    "remark-preset-lint-recommended": "^6.1.3",
+    "@docusaurus/module-type-aliases": "^3.4.0",
+    "@docusaurus/tsconfig": "^3.4.0",
+    "@docusaurus/types": "^3.4.0",
+    "@octokit/rest": "^21.0.0",
+    "@swc/core": "^1.6.5",
+    "@typescript-eslint/eslint-plugin": "^7.13.1",
+    "@typescript-eslint/parser": "^7.13.1",
+    "eslint": "^8.57.0",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-mdx": "^3.1.5",
+    "eslint-plugin-prettier": "^5.1.3",
+    "husky": "^9.0.11",
+    "lint-staged": "^15.2.7",
+    "prettier": "3.3.2",
+    "remark-cli": "^12.0.1",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.0",
+    "remark-lint": "^10.0.0",
+    "remark-lint-final-definition": "^4.0.1",
+    "remark-lint-maximum-heading-length": "^4.0.0",
+    "remark-lint-no-file-name-mixed-case": "^3.0.0",
+    "remark-preset-lint-consistent": "^6.0.0",
+    "remark-preset-lint-markdown-style-guide": "^6.0.0",
+    "remark-preset-lint-recommended": "^7.0.0",
     "remark-preset-prettier": "^2.0.1",
-    "swc-loader": "^0.2.3",
-    "typescript": "^5.0.4"
+    "swc-loader": "^0.2.6",
+    "typescript": "~5.4.5"
   },
   "browserslist": {
     "production": [
@@ -71,7 +72,7 @@
     ]
   },
   "engines": {
-    "node": ">=16.14"
+    "node": ">=18.0"
   },
   "lint-staged": {
     "*.{js,jsx,ts,tsx,md,mdx}": [