Skip to content

Bump docusaurus to v3.9 latest #945

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
martindekov wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Bump docusaurus to v3.9 latest #945

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c710380
Bump docusaurus to v3.9 latest
martindekov Jan 6, 2026
c28cf34
Update README
martindekov Jan 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 1 addition & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# docs.harvesterhci.io

This website is built using [Docusaurus 2](https://docusaurus.io/), a modern
This website is built using [Docusaurus 3](https://docusaurus.io/blog/releases/3.9), a modern
static website generator.

## File Location
Expand Down Expand Up @@ -59,21 +59,6 @@ yarn build
This command generates static content into the `build` directory and can be
served using any static contents hosting service. The build may take a while.

### Generate PDF

First, the docs need to be served on a local dev server. You can do that with:

```console
yarn start > /dev/null 2>&1 &
```

When they are successfully generated and served at `localhost:3000` the PDF can
be generated with

```console
yarn gen-pdf-docs
```

## Deployment

```console
Expand Down
3 changes: 0 additions & 3 deletions babel.config.js
View file
Open in desktop

This file was deleted.

2 changes: 1 addition & 1 deletion docs/troubleshooting/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ After you obtain a copy of the kubeconfig file, run the following script against

:::note

You must replace <VIP\> with the [real VIP](../install/management-address.md#how-to-get-the-vip-mac-address), which is the value of `kube-vip.io/requestedIP` in the link.
You must replace `<VIP>` with the [real VIP](../install/management-address.md#how-to-get-the-vip-mac-address), which is the value of `kube-vip.io/requestedIP` in the link.

:::

Expand Down
35 changes: 11 additions & 24 deletions docusaurus.config.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
// @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');
const {themes} = require('prism-react-renderer');
const lightCodeTheme = themes.github;
const darkCodeTheme = themes.dracula;

/** @type {import('@docusaurus/types').DocusaurusConfig} */
const config = {
Expand All @@ -11,7 +12,11 @@ const config = {
url: "https://docs.harvesterhci.io",
baseUrl: "/",
onBrokenLinks: "warn",
onBrokenMarkdownLinks: "warn",
markdown: {
hooks: {
onBrokenMarkdownLinks: "warn",
},
},
favicon: "img/favicon.ico",
organizationName: "harvester",
projectName: "docs",
Expand All @@ -27,27 +32,9 @@ const config = {
},
},
},
webpack: {
jsLoader: (isServer) => ({
loader: require.resolve("swc-loader"),
Comment on lines -30 to -32
Copy link
Collaborator

@Yu-Jack Yu-Jack Jan 12, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it possible that we switch to swc-loader? 50 minutes build time is too long.

Copy link
Contributor Author

@martindekov martindekov Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the input Jack, this (slower build time) was concerning for me as well, but official docs suggests this. I will try to return configuration of this in combination of experimental feature faster as simply reverting won't work. Compilation breaks so this faster feature need to be fine tuned. Will go over the code in the docosaurus 3.9 and try out some configs and let you know if it works.

Copy link
Contributor Author

@martindekov martindekov Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So with the following config:

  webpack: {
    jsLoader: (isServer) => ({
      loader: require.resolve("swc-loader"),
      options: {
        jsc: {
          parser: {
            syntax: "typescript",
            tsx: true,
          },
          target: "es2019",
          transform: {
            react: {
              runtime: "automatic",
            },
          },
        },
        module: {
          type: isServer ? "commonjs" : "es6",
        },
      },
    }),
  },
  future: {
    v4: true,  
    experimental_faster: {
      swcJsLoader: false,          // using custom webpack.jsLoader above
      swcJsMinimizer: true,        // use js minimzer
      swcHtmlMinimizer: true,      // use html minimzer
      lightningCssMinimizer: true, // use css minimizer
      mdxCrossCompilerCache: true, // use cache
      rspackBundler: false,        // Stay with Webpack (Rspack has perf issues)
    },
  },

I reduced build time to 38 minutes:

mdekov@localhost:~/go/src/github.com/harvester/docs> yarn start
yarn run v1.22.22
$ NODE_OPTIONS='--max-old-space-size=7168' docusaurus start
[INFO] Starting the development server...
[SUCCESS] Docusaurus website is running at: http://localhost:3000/

✔ Client
  Compiled successfully in 38.38m

client (webpack 5.104.1) compiled successfully

So basically between rspack and webpack, webpack is still better but not as fast as the previous runs of ~15-20 minutes. Let me know if you think we can optimize this further. Also the original webpack config as is is not working with 2.4 so that's why it had to be slightly modified to include this new features field in the config.

I'd appreciate if you know someone who can suggest even further optimizations, in my previous tests this was the closes I could get to with webpack.

Copy link
Contributor Author

@martindekov martindekov Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And with the current change as is the build takes around 2150 seconds which is around 35 minutes timed through script, so its more or less the same when building locally webpack vs simply enabling the faster feature and with the pipeline preparation probably it will stilltake ~50-60 minutes for both approaches

Copy link
Contributor Author

@martindekov martindekov Jan 13, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Yu-Jack based on the input above, do you think the slow build time is a deal breaker for adopting the newest docosaurus or we can merge this as is and open separate issue to optimize build times further?

Copy link
Collaborator

@Yu-Jack Yu-Jack Jan 14, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or you can just apply the change to this PR after you find a good method (it would be better). Besides, I think 35 minutes is a good record for right now.

Copy link
Contributor Author

@martindekov martindekov Jan 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I noticed this problem quite early and tried combination of a lot of configurations, the current configuration yielded the best result. In the beginning when I migrated to 3.9 builds took around 1 hour and 30 minutes (locally) so getting it down (again locally) to ~30-35 minutes was success in comparison. So there might be a hidden variable which I missed or certain combination of commands and configurations but best optimization I think is effort on it's own as this change already:

  1. fixes the build with 3.9
  2. fixes the pipeline
  3. migrates the incompatibilities
  4. optimizes best as per documentation suggestions

So I can open separate issue and paste it here before merging this change ?

Copy link
Contributor Author

@martindekov martindekov Jan 14, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@Yu-Jack pipeline is green and this is ready to be merged, I can open a separate issue for this discussion and further optimization? If so can you approve this and we can proceed with merging

Copy link

@slorber slorber Jan 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

With Docusaurus Faster, it's supposed to be faster and you don't need to apply a custom jsLoader: this way Rspack uses it's built-in Rust-based JS loader (no serialization between rust<->js when bundling)

If things are slow, it's worth reporting precisely which step of the build is slow here: facebook/docusaurus#11664 (comment)

Copy link
Contributor Author

@martindekov martindekov Jan 15, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wow thanks for the input @slorber really appreciate it and I did not expect from you to go as far as to review this specific PR so thank you twice. I will run this and report you back

options: {
jsc: {
parser: {
syntax: "typescript",
tsx: true,
},
target: "es2019",
transform: {
react: {
runtime: "automatic",
},
},
},
module: {
type: isServer ? "commonjs" : "es6",
},
},
}),
future: {
v4: true,
experimental_faster: true,
},
themes: ["docusaurus-theme-openapi-docs"],
presets: [
Expand Down
25 changes: 13 additions & 12 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,20 +20,21 @@
"gen-pdf-docs": "docs-to-pdf docusaurus --initialDocURLs='http://localhost:3000' --contentSelector='article' --paginationSelector='a.pagination-nav__link.pagination-nav__link--next' --excludeSelectors='.margin-vert--xl a,[class^='tocCollapsible'],.breadcrumbs,.theme-edit-this-page' --excludePaths='/v1.3/api/' --protocolTimeout=360000 --outputPDFFilename=harvester.pdf"
},
"dependencies": {
"@docusaurus/core": "^2.4.0",
"@docusaurus/plugin-client-redirects": "^2.4.0",
"@docusaurus/plugin-content-blog": "^2.4.0",
"@docusaurus/plugin-content-docs": "^2.4.0",
"@docusaurus/plugin-content-pages": "^2.4.0",
"@docusaurus/plugin-debug": "^2.4.0",
"@docusaurus/preset-classic": "^2.4.0",
"@mdx-js/react": "^1.6.22",
"@docusaurus/core": "^3.9.0",
"@docusaurus/faster": "^3.9.0",
"@docusaurus/plugin-client-redirects": "^3.9.0",
"@docusaurus/plugin-content-blog": "^3.9.0",
"@docusaurus/plugin-content-docs": "^3.9.0",
"@docusaurus/plugin-content-pages": "^3.9.0",
"@docusaurus/plugin-debug": "^3.9.0",
"@docusaurus/preset-classic": "^3.9.0",
"@mdx-js/react": "^3.0.0",
"clsx": "^1.1.1",
"docs-to-pdf": "^0.6.2",
"docusaurus-plugin-image-zoom": "^1.0.0",
"docusaurus-plugin-openapi-docs": "^2.1.2",
"docusaurus-theme-openapi-docs": "^2.1.2",
"prism-react-renderer": "^1.3.1",
"docusaurus-plugin-image-zoom": "^3.0.1",
"docusaurus-plugin-openapi-docs": "^4.5.1",
"docusaurus-theme-openapi-docs": "^4.5.1",
"prism-react-renderer": "^2.4.0",
"react": "^18.2.0",
"react-dom": "^18.2.0",
"remark-cli": "^11.0.0",
Expand Down
4 changes: 3 additions & 1 deletion sidebars.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,8 @@

// @ts-check

const apiSidebar = require("./docs/api/sidebar.ts");

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
docs: [{ type: 'autogenerated', dirName: '.' }],
Expand All @@ -24,7 +26,7 @@ const sidebars = {
description:
"This is the API doc of the Harvester server. The APIs are broken down into the categories below:",
},
items: require("./docs/api/sidebar.js"),
items: apiSidebar.default || apiSidebar,
},
],
};
Expand Down
6 changes: 2 additions & 4 deletions src/theme/DocVersionBanner/index.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,10 @@ import Translate from '@docusaurus/Translate';
import {
useActivePlugin,
useDocVersionSuggestions,
useDocsVersion,
useDocsPreferredVersion,
} from '@docusaurus/plugin-content-docs/client';
import {ThemeClassNames} from '@docusaurus/theme-common';
import {
useDocsPreferredVersion,
useDocsVersion,
} from '@docusaurus/theme-common/internal';
function UnreleasedVersionLabel({siteTitle, versionMetadata}) {
return (
<Translate
Expand Down
2 changes: 1 addition & 1 deletion versioned_docs/version-v1.4/troubleshooting/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ After you obtain a copy of the kubeconfig file, run the following script against

:::note

You must replace <VIP\> with the [real VIP](../install/management-address.md#how-to-get-the-vip-mac-address), which is the value of `kube-vip.io/requestedIP` in the link.
You must replace `<VIP>` with the [real VIP](../install/management-address.md#how-to-get-the-vip-mac-address), which is the value of `kube-vip.io/requestedIP` in the link.

:::

Expand Down
2 changes: 1 addition & 1 deletion versioned_docs/version-v1.5/troubleshooting/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,7 @@ After you obtain a copy of the kubeconfig file, run the following script against

:::note

You must replace <VIP\> with the [real VIP](../install/management-address.md#how-to-get-the-vip-mac-address), which is the value of `kube-vip.io/requestedIP` in the link.
You must replace `<VIP>` with the [real VIP](../install/management-address.md#how-to-get-the-vip-mac-address), which is the value of `kube-vip.io/requestedIP` in the link.

:::

Expand Down
2 changes: 1 addition & 1 deletion versioned_docs/version-v1.6/troubleshooting/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ After you obtain a copy of the kubeconfig file, run the following script against

:::note

You must replace <VIP\> with the [real VIP](../install/management-address.md#how-to-get-the-vip-mac-address), which is the value of `kube-vip.io/requestedIP` in the link.
You must replace `<VIP>` with the [real VIP](../install/management-address.md#how-to-get-the-vip-mac-address), which is the value of `kube-vip.io/requestedIP` in the link.

:::

Expand Down
2 changes: 1 addition & 1 deletion versioned_docs/version-v1.7/troubleshooting/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,7 @@ After you obtain a copy of the kubeconfig file, run the following script against

:::note

You must replace <VIP\> with the [real VIP](../install/management-address.md#how-to-get-the-vip-mac-address), which is the value of `kube-vip.io/requestedIP` in the link.
You must replace `<VIP>` with the [real VIP](../install/management-address.md#how-to-get-the-vip-mac-address), which is the value of `kube-vip.io/requestedIP` in the link.

:::

Expand Down
Loading