Docusaurus Upgrade v3.1.1 #1139

sunilarjun · 2024-02-22T21:10:01Z

Description

Upgrades the Docusaurus version to 3.1.1. The following actions were performed to facilitate the upgrade:

Your local machine will need to have installed node.js >=18.x.

The docs, i18n/zh, and versioned_docs folders all received markdown fixes against the Docusaurus upgrade from MDX v2 to MDX v3. The new version has stricter linting rules, and the following guide was used to assist with upgrading: https://docusaurus.io/docs/migration/v3.

The package.json file had the core Docusaurus dependencies updated as well as React and Postcss:

"@docusaurus/core": "^3.1.1"
"@docusaurus/plugin-client-redirects": "^3.1.1"
"@docusaurus/preset-classic": "^3.1.1"
"@mdx-js/react": "^3.0.1"
"react": "^18.0.0"
"react-dom": "^18.2.0"
"@docusaurus/module-type-aliases": "^3.1.1"

Additionally, the heap size was increased in the deploy.yml and test-deploy.yml workflow files to fix a JS heap OOM error being seen.

Comments

I think due to the large amount of files changed, reviewers can call out the sections they are reviewing in the comments so as to not double up on sections reviewed.

…for upgrading Docusaurus to 3.1.1 Signed-off-by: Sunil Singh <sunil.singh@suse.com>

Signed-off-by: Sunil Singh <sunil.singh@suse.com>

martyav · 2024-02-26T21:54:45Z

I'm going to check out the branch and look at a local build of the site. For my initial pas, I'll cover the pages in How-to Guides and Integrations in the English version of latest

martyav

This was my first pass at it, covering 8 pages in the English version of latest. I'll return for more passes, probably taking on ~10-20 pages at a time

martyav · 2024-02-26T22:44:21Z

...cation-permissions-and-global-configuration/authentication-config/configure-keycloak-saml.md

Having some trouble flagging this, but the example on line 158 needs backticks:

You can generate a key/certificate pair using an openssl command. For example:

openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert

martyav · 2024-02-26T22:46:58Z

docs/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md

Line 27 needs backticks:

If you do not specify a pre-shared secret, RKE2 will generate one and place it at /var/lib/rancher/rke2/server/node-token.

martyav · 2024-02-26T22:49:12Z

docs/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md

        token: my-shared-secret
        server: https://<DNS-DOMAIN>:9345
        tls-san:
          - my-kubernetes-domain.com
          - another-kubernetes-domain.com
+        ```
+
 After that, you need to run the installer and enable, then start, rke2:

        curl -sfL https://get.rke2.io | sh -


This line needs triple backticks

curl -sfL https://get.rke2.io | sh -

martyav · 2024-02-26T22:53:36Z

...to-guides/new-user-guides/kubernetes-clusters-in-rancher-setup/register-existing-clusters.md

@@ -222,15 +222,17 @@ Authorized Cluster Endpoint (ACE) support has been added for registered RKE2 and
    ```

 2. Add the following to the config file (or create one if it doesn’t exist); note that the default location is `/etc/rancher/{rke2,k3s}/config.yaml`:
-    ```yaml
+    ```console


Is console the Docusaurus3 equivalent for yaml?

martyav · 2024-02-26T23:02:36Z

docs/integrations-in-rancher/fleet/use-fleet-behind-a-proxy.md

-| `HTTP_PROXY` | http://<PROXY_IP>:8888 |
-| `HTTPS_PROXY` | http://<PROXY_IP>:8888
+| `HTTP_PROXY` | `http://<PROXY_IP>:8888` |
+| `HTTPS_PROXY` | `http://<PROXY_IP>:8888`|
 | `NO_PROXY`     | 127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local |


It feels like each of the values listed here should have backticks:

127.0.0.0/8, 10.0.0.0/8, etc

martyav · 2024-02-26T23:05:55Z

docs/integrations-in-rancher/monitoring-and-alerting/promql-expressions.md

This section (Node Network Packet) has strikethroughs:

martyav · 2024-02-26T23:06:50Z

docs/integrations-in-rancher/monitoring-and-alerting/promql-expressions.md

Node Network I/O also has strikethroughs.

martyav · 2024-02-26T23:11:46Z

docs/integrations-in-rancher/monitoring-and-alerting/promql-expressions.md

Congrats on fixing these, btw, HTML tables within tables are not easy to read!

btat · 2024-02-26T22:26:49Z

...tent-docs/current/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md

        token: my-shared-secret
        server: https://<DNS-DOMAIN>:9345
        tls-san:
          - my-kubernetes-domain.com
          - another-kubernetes-domain.com
+          ```


Suggested change

```

```

Misaligned with the starting set of backticks.

btat · 2024-02-26T22:40:11Z

...n-content-docs/current/integrations-in-rancher/monitoring-and-alerting/promql-expressions.md

@@ -99,15 +99,15 @@ title: PromQL 表达式参考

 | Catalog | 表达式 |
 | --- | --- |
-| 详情 | <table><tr><td>receive-dropped</td><td><code>sum(rate(node_network_receive_drop_total{device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"}[5m])) by (device)</code></td></tr><tr><td>receive-errs</td><td><code>sum(rate(node_network_receive_errs_total{device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"}[5m])) by (device)</code></td></tr><tr><td>receive-packets</td><td><code>sum(rate(node_network_receive_packets_total{device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"}[5m])) by (device)</code></td></tr><tr><td>transmit-dropped</td><td><code>sum(rate(node_network_transmit_drop_total{device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"}[5m])) by (device)</code></td></tr><tr><td>transmit-errs</td><td><code>sum(rate(node_network_transmit_errs_total{device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"}[5m])) by (device)</code></td></tr><tr><td>transmit-packets</td><td><code>sum(rate(node_network_transmit_packets_total{device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"}[5m])) by (device)</code></td></tr></table> |
-| 摘要 | <table><tr><td>receive-dropped</td><td><code>sum(rate(node_network_receive_drop_total{device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"}[5m]))</code></td></tr><tr><td>receive-errs</td><td><code>sum(rate(node_network_receive_errs_total{device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"}[5m]))</code></td></tr><tr><td>receive-packets</td><td><code>sum(rate(node_network_receive_packets_total{device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"}[5m]))</code></td></tr><tr><td>transmit-dropped</td><td><code>sum(rate(node_network_transmit_drop_total{device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"}[5m]))</code></td></tr><tr><td>transmit-errs</td><td><code>sum(rate(node_network_transmit_errs_total{device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"}[5m]))</code></td></tr><tr><td>transmit-packets</td><td><code>sum(rate(node_network_transmit_packets_total{device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"}[5m]))</code></td></tr></table> |
+| 详情 | <table><tr><td>receive-dropped</td><td><code>sum(rate(node_network_receive_drop_total&#123;device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"&#125;[5m])) by (device)</code></td></tr><tr><td>receive-errs</td><td><code>sum(rate(node_network_receive_errs_total&#123;device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"&#125;[5m])) by (device)</code></td></tr><tr><td>receive-packets</td><td><code>sum(rate(node_network_receive_packets_total&#123;device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"&#125;[5m])) by (device)</code></td></tr><tr><td>transmit-dropped</td><td><code>sum(rate(node_network_transmit_drop_total&#123;device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"&#125;[5m])) by (device)</code></td></tr><tr><td>transmit-errs</td><td><code>sum(rate(node_network_transmit_errs_total&#123;device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"&#125;[5m])) by (device)</code></td></tr><tr><td>transmit-packets</td><td><code>sum(rate(node_network_transmit_packets_total&#123;device!~"lo &#124; veth.&ast; &#124; docker.&ast; &#124; flannel.&ast; &#124; cali.&ast; &#124; cbr.&ast;",instance=~"$instance"&#125;[5m])) by (device)</code></td></tr></table> |


Is tilde an invalid character itself or does it depend on the context around it?

Earlier occurrences of device!~"lo were changed to device!~"lo, but the occurrences in this block aren't changed. Also, there are many occurrences of instance=~ if the character itself is the issue.

This is likely applicable for the English docs as well.

btat · 2024-02-26T22:59:18Z

...-docs/version-2.8/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md

        token: my-shared-secret
        server: https://<DNS-DOMAIN>:9345
        tls-san:
          - my-kubernetes-domain.com
          - another-kubernetes-domain.com
+          ```


Suggested change

```

```

martyav

Covered up to i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-saml.md (14 pages)

I noticed a strange problem with how section headers that contain colons are handled. For the purposes of the right-hand TOC and links, everything after the colon is ignored until there's a space and then it's rendered as normal, so things like "1.1.2 Ensure that the API server pod specification file ownership is set to root:root (Automated)" get rendered as "[...] set to root (Automated)". This isn't a huge deal, but it could break bookmarks to the affected sections.

martyav · 2024-02-27T22:27:42Z

...y/hardening-guides/k3s-hardening-guide/k3s-self-assessment-guide-with-cis-v1.23-k8s-v1.23.md

When I compared this page with the current page, there was a tiny difference in the right TOC. For some reason, the term "root:root" is only rendering as "root" (nothing after colon) there.

Also, the URLs for those sections differ from the current. "112-ensure-that-the-api-server-pod-specification-file-ownership-is-set-to-rootroot-automated" for current, "112-ensure-that-the-api-server-pod-specification-file-ownership-is-set-to-root-automated" for 3.1.1. This is not hugely important except it could break users' bookmarks.

v3.1.1 ->

Current ->

martyav · 2024-02-27T22:32:24Z

...y/hardening-guides/k3s-hardening-guide/k3s-self-assessment-guide-with-cis-v1.23-k8s-v1.23.md

@@ -123,7 +123,7 @@ chown root:root /etc/kubernetes/manifests/etcd.yaml

 **Remediation:**
 Run the below command (based on the file location on your system) on the control plane node.
-For example, chmod 644 <path/to/cni/files\>
+For example, `chmod 644 <path/to/cni/files\>`


There are numerous examples throughout the page similar to this line, and imo either they should all get backticks or none of them should. Same with the other markup added. It's a long page and the current version doesn't include that markup, however since these are all commands to enter verboten, they should have backticks according to our style guide. I'm not sure if it's worth the effort unless you can use regex to find all the commands and apply the proper markup.

martyav · 2024-02-27T22:38:30Z

...y/hardening-guides/k3s-hardening-guide/k3s-self-assessment-guide-with-cis-v1.24-k8s-v1.24.md

This page has similar issues as noted for the previous one, including how headings with colons are being rendered in a weird way in the sidebar/urls.

martyav · 2024-02-27T22:48:46Z

...-guides/k3s-hardening-guide/k3s-self-assessment-guide-with-cis-v1.7-k8s-v1.25-v1.26-v1.27.md

And same as the previous 2. I'm not sure if updating this page with coding backticks is worth the amount of time involved. The section links differing from the current is more of a concern, but if we can't figure out why "root:root" is being rendered in a weird way, at least the user will land on the correct page (if not the correct part of the page)

martyav · 2024-02-27T22:51:14Z

...hardening-guides/rke1-hardening-guide/rke1-self-assessment-guide-with-cis-v1.23-k8s-v1.23.md

It seems like all of the self-assessment guides have similar minor issues, so I won't repeat myself. Just making a note of it.

btat · 2024-02-27T23:33:19Z

For the self-assessment pages, we'll want to sync with the Security team. They use a script to generate that content, so if it can be fixed at the source that'll be better than us trying to manually catch it a new guide comes out.

btat · 2024-02-27T23:39:01Z

Covered up to i18n/zh/docusaurus-plugin-content-docs/current/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-keycloak-saml.md (14 pages)

I noticed a strange problem with how section headers that contain colons are handled. For the purposes of the right-hand TOC and links, everything after the colon is ignored until there's a space and then it's rendered as normal, so things like "1.1.2 Ensure that the API server pod specification file ownership is set to root:root (Automated)" get rendered as "[...] set to root (Automated)". This isn't a huge deal, but it could break bookmarks to the affected sections.

The colon issue is likely https://docusaurus.io/docs/next/migration/v3#unintended-usage-of-directives.

martyav · 2024-02-28T21:48:43Z

...tent-docs/current/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md

        token: my-shared-secret
        server: https://<DNS-DOMAIN>:9345
        tls-san:
          - my-kubernetes-domain.com
          - another-kubernetes-domain.com
+          ```
 运行安装程序，然后启用并启动 RKE2：

        curl -sfL https://get.rke2.io | sh -


This should get backticks

martyav · 2024-02-28T22:03:28Z

...n-content-docs/current/integrations-in-rancher/monitoring-and-alerting/promql-expressions.md

节点网络数据包 suffers from the strikethrough problem. 节点网络 I/O too

martyav · 2024-02-28T22:15:32Z

...cation-permissions-and-global-configuration/authentication-config/configure-keycloak-saml.md

The command, openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert (in an admonition) should get backticks

martyav · 2024-02-28T22:18:29Z

...-docs/version-2.6/how-to-guides/new-user-guides/kubernetes-cluster-setup/rke2-for-rancher.md

        token: my-shared-secret
        server: https://<DNS-DOMAIN>:9345
        tls-san:
          - my-kubernetes-domain.com
          - another-kubernetes-domain.com
+          ```
 运行安装程序，然后启用并启动 RKE2：

        curl -sfL https://get.rke2.io | sh -


This line should get backticks

martyav · 2024-02-28T22:34:14Z

...t-docs/version-2.6/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.md

-| `HTTP_PROXY` | http://<PROXY_IP>:8888 |
-| `HTTPS_PROXY` | http://<PROXY_IP>:8888 |
+| `HTTP_PROXY` | `http://<PROXY_IP>:8888` |
+| `HTTPS_PROXY` | `http://<PROXY_IP>:8888` |
 | `NO_PROXY` | 127.0.0.0/8,10.0.0.0/8,172.16.0.0/12,192.168.0.0/16,.svc,.cluster.local |


Similar comment as elsewhere about surrounding these values with backticks

martyav · 2024-02-28T22:37:54Z

I covered up through i18n/zh/docusaurus-plugin-content-docs/version-2.6/integrations-in-rancher/fleet-gitops-at-scale/use-fleet-behind-a-proxy.md (about 15 files), but since they're the same files (just in Chinese), they have similar issues.

sunilarjun added 4 commits February 22, 2024 13:01

Updated MDX in English docs pages and upgraded certain node packages …

5335520

…for upgrading Docusaurus to 3.1.1 Signed-off-by: Sunil Singh <sunil.singh@suse.com>

Updating the MDX errors for the translations.

16436be

Signed-off-by: Sunil Singh <sunil.singh@suse.com>

Fixing MDX error for translation of registering clusters page.

ac914a8

Signed-off-by: Sunil Singh <sunil.singh@suse.com>

Bumping heap size to trigger build again.

b02b477

Signed-off-by: Sunil Singh <sunil.singh@suse.com>

btat mentioned this pull request Feb 23, 2024

Bump Docusaurus #867

Closed

sunilarjun marked this pull request as ready for review February 26, 2024 18:58

sunilarjun requested review from btat, LucasSaintarbor and martyav as code owners February 26, 2024 18:58

martyav requested changes Feb 26, 2024

View reviewed changes

btat requested changes Feb 26, 2024

View reviewed changes

martyav reviewed Feb 27, 2024

View reviewed changes

martyav requested changes Feb 28, 2024

View reviewed changes

sunilarjun added 3 commits March 7, 2024 12:33

Merge branch 'rancher:main' into docusaurus-v3

9fc4582

Merge branch 'rancher:main' into docusaurus-v3

d6ab032

Merge branch 'rancher:main' into docusaurus-v3

3d901f9

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docusaurus Upgrade v3.1.1 #1139

Docusaurus Upgrade v3.1.1 #1139

sunilarjun commented Feb 22, 2024 •

edited

martyav commented Feb 26, 2024

martyav left a comment

martyav Feb 26, 2024

martyav Feb 26, 2024

martyav Feb 26, 2024

martyav Feb 26, 2024

martyav Feb 26, 2024

martyav Feb 26, 2024

martyav Feb 26, 2024

martyav Feb 26, 2024

btat Feb 26, 2024

btat Feb 26, 2024

btat Feb 26, 2024

martyav left a comment •

edited

martyav Feb 27, 2024

martyav Feb 27, 2024

martyav Feb 27, 2024 •

edited

martyav Feb 27, 2024

martyav Feb 27, 2024

btat commented Feb 27, 2024

btat commented Feb 27, 2024

martyav Feb 28, 2024

martyav Feb 28, 2024

martyav Feb 28, 2024

martyav Feb 28, 2024

martyav Feb 28, 2024

martyav commented Feb 28, 2024

Docusaurus Upgrade v3.1.1 #1139

Are you sure you want to change the base?

Docusaurus Upgrade v3.1.1 #1139

Conversation

sunilarjun commented Feb 22, 2024 • edited

Description

Comments

martyav commented Feb 26, 2024

martyav left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

martyav left a comment • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

martyav Feb 27, 2024 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

btat commented Feb 27, 2024

btat commented Feb 27, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

martyav commented Feb 28, 2024

sunilarjun commented Feb 22, 2024 •

edited

martyav left a comment •

edited

martyav Feb 27, 2024 •

edited