feat: enable faster Docusaurus builds and clarify beta rollback (#443)

## Summary
- enable Docusaurus Faster with the required v4 compatibility flag and
lockfile updates
- fix the repo TypeScript/editor issues that surfaced while validating
the config change
- clarify the 7.3.0-beta.2 rollback guidance for TPM/internal boot users
and update AGENTS.md so full builds are allowed when explicitly
requested

## Validation
- pnpm exec tsc --noEmit
- pnpm run build

## Build notes
- the full build now passes
- Docusaurus still emits existing content warnings for broken links,
broken anchors, and nested HTML tags in docs content across locales
- Docusaurus also warns that `siteConfig.onBrokenMarkdownLinks` is
deprecated and that `babel.config.js` can be removed when using the SWC
loader


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Documentation**
* Updated rollback guidance with more flexible recovery options for
recent releases.
  * Clarified repository validation directives.

* **Chores**
  * Enabled build performance optimizations and faster bundling.
  * Updated TypeScript configuration for improved type checking.
  * Added dependency to support optimized build processes.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: elibosley

AGENTS.md

@@ -2,6 +2,6 @@
 
 ## Validation
 
-- Never validate changes in this repo by running the full build.
+- Do not validate changes in this repo by running the full build unless the user explicitly asks for it.
 - The build is intentionally considered too expensive and inefficient for routine validation.
 - Prefer targeted verification instead, such as reviewing the changed files, running narrow checks relevant to the edit, or using lightweight local validation where available.

docs/unraid-os/release-notes/7.3.0.md

@@ -18,11 +18,12 @@ See [Unraid OS Prerelease (Bugs & Feedback)](https://product.unraid.net/b/unraid
 
 ### Rolling back
 
-- Once you enable internal boot or switch to TPM-based licensing, you cannot roll back to an earlier release.
+- If you already enabled internal boot or switched to TPM-based licensing while testing the 7.3 prerelease, you can roll back to `7.3.0-beta.1` without issue.
+- Do not roll back to `7.2.4` or earlier after enabling internal boot or TPM-based licensing.
 - If you upgrade ZFS pool features, earlier Unraid releases may not be able to import those pools.
 - If you need to roll back, follow the normal prerelease rollback process before moving between builds.
 
-If rolling back earlier than 7.2.4, also see the [7.2.4 release notes](/unraid-os/release-notes/7.2.4/).
+If you are considering any rollback path below `7.3.0-beta.1`, also see the [7.2.4 release notes](/unraid-os/release-notes/7.2.4/).
 
 ## Changes vs. 7.3.0-beta.1
 

docusaurus.config.ts

@@ -76,6 +76,21 @@ const config: Config = {
     defaultLocale: DEFAULT_LOCALE,
     locales: ["en", "es", "fr", "de", "zh"],
   },
+  future: {
+    v4: {
+      removeLegacyPostBuildHeadAttribute: true,
+    },
+    experimental_faster: {
+      swcJsLoader: true,
+      swcJsMinimizer: true,
+      swcHtmlMinimizer: true,
+      lightningCssMinimizer: true,
+      mdxCrossCompilerCache: true,
+      rspackBundler: true,
+      rspackPersistentCache: true,
+      ssgWorkerThreads: true,
+    },
+  },
   scripts: [
     {
       src: "/js/redirects.js",
@@ -430,7 +445,7 @@ const config: Config = {
           },
           {
             from: "/unraid-os/faq/redeem-license-activation-code/",
-            to: "/unraid-account/redeem-activation-code/", 
+            to: "/unraid-account/redeem-activation-code/",
           },
           {
             from: "/unraid-os/faq/unraid-account/",

package.json

@@ -28,6 +28,7 @@
   "dependencies": {
     "@crowdin/cli": "^4.14.0",
     "@docusaurus/core": "3.9.2",
+    "@docusaurus/faster": "3.9.2",
     "@docusaurus/plugin-client-redirects": "^3.9.2",
     "@docusaurus/plugin-content-docs": "3.9.2",
     "@docusaurus/plugin-ideal-image": "^3.9.2",

pnpm-lock.yaml

@@ -1,16 +1,6 @@
-declare module "./sidebar-semver-sort.js" {
-  // Use the Docusaurus SidebarItem type when available so TypeScript understands
-  // the shape of the items passed into the sorter.
-  import type { SidebarItem } from "@docusaurus/plugin-content-docs";
+import type { SidebarItem } from "@docusaurus/plugin-content-docs";
 
-  /**
-   * Sorts the array of sidebar items. The implementation may return categories
-   * (with nested items) or a flat list depending on the sortBySemver flag.
-   */
-  export function sortSidebarItems(
-    items: SidebarItem[],
-    sortBySemver?: boolean
-  ): SidebarItem[];
-
-  export {};
-}
+export function sortSidebarItems(
+  items: SidebarItem[],
+  sortBySemver?: boolean,
+): SidebarItem[];

sidebar-semver-sort.d.ts

@@ -1,17 +1,17 @@
-import React from 'react';
-import clsx from 'clsx';
-import styles from './styles.module.css';
+import React from "react";
+import clsx from "clsx";
+import styles from "./styles.module.css";
 
 type FeatureItem = {
   title: string;
-  Svg: React.ComponentType<React.ComponentProps<'svg'>>;
-  description: JSX.Element;
+  Svg: React.ComponentType<React.ComponentProps<"svg">>;
+  description: React.ReactNode;
 };
 
 const FeatureList: FeatureItem[] = [
   {
-    title: 'Easy to Use',
-    Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default,
+    title: "Easy to Use",
+    Svg: require("@site/static/img/undraw_docusaurus_mountain.svg").default,
     description: (
       <>
         Docusaurus was designed from the ground up to be easily installed and
@@ -20,8 +20,8 @@ const FeatureList: FeatureItem[] = [
     ),
   },
   {
-    title: 'Focus on What Matters',
-    Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default,
+    title: "Focus on What Matters",
+    Svg: require("@site/static/img/undraw_docusaurus_tree.svg").default,
     description: (
       <>
         Docusaurus lets you focus on your docs, and we&apos;ll do the chores. Go
@@ -30,8 +30,8 @@ const FeatureList: FeatureItem[] = [
     ),
   },
   {
-    title: 'Powered by React',
-    Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,
+    title: "Powered by React",
+    Svg: require("@site/static/img/undraw_docusaurus_react.svg").default,
     description: (
       <>
         Extend or customize your website layout by reusing React. Docusaurus can
@@ -41,9 +41,9 @@ const FeatureList: FeatureItem[] = [
   },
 ];
 
-function Feature({title, Svg, description}: FeatureItem) {
+function Feature({ title, Svg, description }: FeatureItem) {
   return (
-    <div className={clsx('col col--4')}>
+    <div className={clsx("col col--4")}>
       <div className="text--center">
         <Svg className={styles.featureSvg} role="img" />
       </div>
@@ -55,7 +55,7 @@ function Feature({title, Svg, description}: FeatureItem) {
   );
 }
 
-export default function HomepageFeatures(): JSX.Element {
+export default function HomepageFeatures(): React.JSX.Element {
   return (
     <section className={styles.features}>
       <div className="container">

src/components/HomepageFeatures/index.tsx

@@ -0,0 +1,7 @@
+import "react";
+
+declare module "react" {
+  interface IframeHTMLAttributes<T> {
+    credentialless?: boolean;
+  }
+}

src/types/react-augmentations.d.ts

@@ -2,6 +2,13 @@
   // This file is not used in compilation. It is here just for a nice editor experience.
   "extends": "@tsconfig/docusaurus/tsconfig.json",
   "compilerOptions": {
-    "baseUrl": "."
+    "baseUrl": ".",
+    "jsx": "react-jsx",
+    "types": [
+      "node",
+      "react",
+      "@docusaurus/module-type-aliases",
+      "@docusaurus/theme-classic"
+    ]
   }
 }