This PR seeks to bump Docusaurus from v3.0.0-alpha.0 to v3.4.0, as well as most other dependencies and all GitHub actions.
There is a test run of the pipeline and the generated pages for comparison.
Local builds (including API) and starting the server with Docker succeeded as well.
Please let me know if something needs to change or you spot other anomalies.
Differences
Visuals
Warning admonitions are now orange instead of red. Making them look like Caution (which is now deprecated) instead of Danger
Code highlighting changes: added 'bash' to Lanuages for '```shell' highlighting as it was removed from the default list
Build Errors
{curly brackets} are used for the new expression feature of mdx v2, leading to e.g. ReferenceErrors inImVector{T} because T is undefined.
There are multiple remedies:
Use the new experimentalCommonMark mode that compiles *.md with CommonMark and *.mdx with mdx. This supposedly becomes default in the future - and is the solution chosen for now
PR a change that escapes curly brackets to DocFxMarkdownGen, the tool used to turn docfx metadata into markdown files - i have a working modification, but didn't test for unwanted consequences
Escape them right in the comments in Dalamud, and somehow make sure they will always be escaped in the future
<br> need to close <br/> in newer versions of mdx/docusaurus
Other changes
Replaced :::caution with :::warning due to deprecation of the former (1 occurrence)
docusaurus.config.js is now a ES Module as recommended by the migration guide
Reasons
Keeping dependencies up to date. Future proofing.
Docusaurus
Docusaurus offers various new features and improvements:
All dependency updates are a direct result of Docusaurus v3.
Dev Dependencies:
Some were caused by Docusaurus as well, e.g. @docusaurus/*, eslint-plugin-mdx for mdx 3 support
Some are only minor version changes: e.g. @swc/* and TypeScript
Husky v8 -> v9: while it remains v8 compatible, was migrated to v9
Bumped all linters and remark rules to their latest version - no breaking changes that concern us from what i saw
Bumped pnpm to v9.4.0 for security fixes and feature improvements, e.g. actually checking the packageManager field to check if the correct version is used.
GitHub Actions
On June 30th 2024, we will change the default from Node16 to Node20.
Timeline Blog Post
While there is a flag to continue using Node 16 in the runner for some time, this PR updated all used actions to their latest versions, using Node 20. Docusaurus now also requires Node >= 18, making this change sensible now.
This PR seeks to bump Docusaurus from
v3.0.0-alpha.0tov3.4.0, as well as most other dependencies and all GitHub actions.There is a test run of the pipeline and the generated pages for comparison.
Local builds (including API) and starting the server with Docker succeeded as well.
Please let me know if something needs to change or you spot other anomalies.
Differences
Visuals
<summary>tag looks like an expandable admonition, instead of a expandable line making them much easier to seeBuild Errors
{curly brackets}are used for the new expression feature of mdx v2, leading to e.g. ReferenceErrors inImVector{T}because T is undefined.There are multiple remedies:
*.mdwith CommonMark and*.mdxwith mdx. This supposedly becomes default in the future - and is the solution chosen for now<br>need to close<br/>in newer versions of mdx/docusaurusOther changes
:::cautionwith:::warningdue to deprecation of the former (1 occurrence)docusaurus.config.jsis now a ES Module as recommended by the migration guideReasons
Keeping dependencies up to date. Future proofing.
Docusaurus
Docusaurus offers various new features and improvements:
Other Dependencies
All dependency updates are a direct result of Docusaurus v3.
Dev Dependencies:
@docusaurus/*,eslint-plugin-mdxfor mdx 3 support@swc/*andTypeScriptHuskyv8 -> v9: while it remains v8 compatible, was migrated to v9Bumped pnpm to v9.4.0 for security fixes and feature improvements, e.g. actually checking the packageManager field to check if the correct version is used.
GitHub Actions
Timeline Blog Post While there is a flag to continue using Node 16 in the runner for some time, this PR updated all used actions to their latest versions, using Node 20. Docusaurus now also requires Node >= 18, making this change sensible now.