feat(docs): Replace Hugo with Docusaurus (#22990)

# Docusaurus

Updates the website (/docs) to leverage
[Docusaurus](https://docusaurus.io/) in place of Hugo as its static site
generator.

## Functional changes

### Versioning

The existing Hugo-based site only has a partial versioning story.
The API docs are versioned, but the rest of the content isn't.
This creates a messy story where our hand-written docs likely only
discuss topics related to the current version, and we have no place to
put docs discussing earlier versions.
Or, even worse, we have a mixed bag of documentation for different
versions, creating a very unclear user story.

This prototype includes an end-to-end versioning story, [automated by
Docusaurus](https://docusaurus.io/docs/versioning).
Current (v2) docs live under `docs`.
Old (v1) docs live under `versioned_docs/version-1`.

Most of the documentation has been duplicated between the two versions,
but some minor changes have been made to make the docs better line up
with the corresponding version of the API.
These changes should be reviewed before being merged into main /
deploying the new website.

### Search

This branch includes an offline implementation of search.
An offline solution comes with some downsides (slower build, larger
bundle), and probably isn't what we want long term.
That said, it is much better than what our current website has (no
search whatsoever).

We should come back to this after v1 of our new website.

---------

Co-authored-by: Wayne Ferrao <wayneferrao@microsoft.com>

Author: Josmithr

.github/workflows/website-validation.yml

@@ -20,6 +20,8 @@ permissions:
 
 jobs:
 
+  # Build the website (including API documentation).
+  # Publish the build artifact for subsequent jobs to leverage.
   build_site:
     runs-on: ubuntu-latest
     name: Build site
@@ -36,15 +38,16 @@ jobs:
       - name: Build site artifact
         run: |
           pnpm i --frozen-lockfile
-          npm run ci:build
+          npm run build
       - name: Upload site artifact
         # release notes: https://github.com/actions/upload-artifact/releases/tag/v4.4.3
         uses: actions/upload-artifact@b4b15b8c7c6ac21ea08fcf65892d2ee8f75cf882 # ratchet:actions/upload-artifact@v4
         with:
           name: fluidframework-site
-          path: docs/public
+          path: docs/build
           retention-days: 3
 
+  # Run linter checks against the website content and infrastructure.
   lint:
     runs-on: ubuntu-latest
     name: pnpm lint
@@ -63,6 +66,35 @@ jobs:
           pnpm i --frozen-lockfile
           pnpm lint
 
+  # Run the website's tests.
+  test:
+    runs-on: ubuntu-latest
+    name: 🧪 Website Tests
+    needs: build_site
+    steps:
+      - uses: actions/checkout@f43a0e5ff2bd294095638e18286ca9a3d1956744 # ratchet:actions/checkout@v3
+        with:
+          submodules: false
+      - uses: pnpm/action-setup@fe02b34f77f8bc703788d5817da081398fad5dd2 # ratchet:pnpm/action-setup@v4
+      - uses: actions/setup-node@1a4442cacd436585916779262731d5b162bc6ec7 # ratchet:actions/setup-node@v3
+        with:
+          node-version: "18"
+          cache: "pnpm"
+          cache-dependency-path: docs/pnpm-lock.yaml
+
+      - name: Download site artifact
+         # release notes: https://github.com/actions/download-artifact/releases/tag/v4.1.8
+        uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # ratchet:actions/download-artifact@v4
+        with:
+          name: fluidframework-site
+          path: docs/build
+      - name: Install dependencies
+        run: "pnpm i --frozen-lockfile"
+      - name: Run tests
+        run: "npm run test"
+
+  # Run the link checker against the website.
+  # Publish the results to the PR as a comment.
   broken_link_check:
     runs-on: ubuntu-latest
     name: 🔗 Broken Link Check
@@ -85,15 +117,15 @@ jobs:
         uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # ratchet:actions/download-artifact@v4
         with:
           name: fluidframework-site
-          path: docs/public
+          path: docs/build
       - name: Install dependencies
         run: "pnpm i --frozen-lockfile"
       - name: Check for broken links
         id: linkcheck
         continue-on-error: true
         run: |
           set -o pipefail
-          pnpm run ci:linkcheck | tee ./results/linkcheck-output.txt
+          pnpm run ci:check-links | tee ./results/linkcheck-output.txt
 
       - name: Save PR number
         run: echo ${{ github.event.number }} > ./results/pr

.prettierignore

@@ -80,28 +80,18 @@ packages/framework/data-object-base/es5
 # Generated by policy-check
 packages/runtime/test-runtime-utils/src/assertionShortCodesMap.ts
 
-# Ignore all HTML files in docs since they're go templates
-docs/**/*.html
-
-# Ignore docs markdown files since those are formatted using markdownlint
-docs/**/*.md
-
-# Ignore docs markdown files since those are formatted using markdownlint
-docs/**/*.yaml
-docs/**/*.yml
-
-# This is a generated file
-docs/themes/thxvscode/assets/js/bundle.js
-
-# Ignore these scss files
-docs/themes/thxvscode/assets/scss/*
+# TODO: Remove these *after* merging new site infra into main, to ensure docs diff is intelligable during PR review.
+docs/docs/*
+docs/versioned_docs/*
 
 # Generated
-docs/_doc-models
-docs/data/v*
-docs/public
-docs/resources
-docs/static/staticwebapp.config.json
+docs/.doc-models
+docs/.docusaurus
+docs/build
+docs/versions.json
+
+# Formatting gets clobbered by swa
+docs/swa-cli.config.json
 
 # This is a test file
 tools/markdown-magic/test/include.md

.vscode/extensions.json

@@ -7,6 +7,8 @@
 		"dbaeumer.vscode-eslint",
 		"esbenp.prettier-vscode",
 		"ms-azure-devops.azure-pipelines",
+		"xyc.vscode-mdx-preview",
+		"unifiedjs.vscode-mdx",
 	],
 	// List of extensions recommended by VS Code that should not be recommended for users of this workspace.
 	"unwantedRecommendations": [],

docs/.env.template

@@ -0,0 +1,7 @@
+# `.env` file template.
+# Copy these contents into a local `.env` file in this directoy and fill in the values as needed.
+# `.env` is configured to be git-ignored. Please do not override this behavior.
+
+# Flag that determines whether or not repo-local API documentation should be generated and included in the site build.
+# Only used in local development.
+LOCAL_API_DOCS=<boolean>

docs/.eslintrc.cjs

@@ -0,0 +1,81 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+module.exports = {
+	extends: [require.resolve("@fluidframework/eslint-config-fluid"), "prettier"],
+	parserOptions: {
+		project: ["./tsconfig.json"],
+	},
+	settings: {
+		react: {
+			version: "detect",
+		},
+	},
+	rules: {
+		// Required by Docusaurus for certain component exports.
+		"import/no-default-export": "off",
+
+		"import/no-unassigned-import": [
+			"error",
+			{
+				// Allow unassigned imports of css files.
+				allow: ["**/*.css"],
+			},
+		],
+
+		"import/no-internal-modules": [
+			"error",
+			{
+				allow: ["@docusaurus/**", "@site/**", "@theme/**"],
+			},
+		],
+
+		"import/no-unresolved": [
+			"error",
+			{
+				ignore: ["^@docusaurus/", "^@theme/", "^@theme-original/"],
+			},
+		],
+
+		"import/no-extraneous-dependencies": [
+			"error",
+			{
+				devDependencies: ["test/**"],
+			},
+		],
+
+		// Unfortunately, some of the import aliases supported by Docusaurus are not recognized by TSC / the eslint parser.
+		// So we have to disable some rules that enforce strong typing.
+		// Could be worth investigating if there's a way to make TSC aware of how the aliases are resolved, but until then,
+		// these rules are disabled.
+		"@typescript-eslint/no-unsafe-argument": "off",
+		"@typescript-eslint/no-unsafe-assignment": "off",
+		"@typescript-eslint/no-unsafe-call": "off",
+		"@typescript-eslint/no-unsafe-member-access": "off",
+	},
+	overrides: [
+		{
+			// Test files
+			files: ["test/**/*"],
+			parserOptions: {
+				project: ["./test/tsconfig.json"],
+			},
+		},
+		{
+			// Config files
+			files: ["docusaurus.config.ts", "playwright.config.ts", "infra/**/*"],
+			rules: {
+				// Dev dependencies and internal modules may be used in config files
+				"import/no-extraneous-dependencies": [
+					"error",
+					{
+						devDependencies: true,
+					},
+				],
+				"import/no-internal-modules": "off",
+			},
+		},
+	],
+};

docs/.gitignore

@@ -1,21 +1,34 @@
-.hugo_build.lock
-assets/doc-models/*.json
-bin/
-content/docs/api
-node_modules/
-public/
-scripts/api-documenter/temp
-themes/thxvscode/assets/js/node_modules/
+.env
 
-# Temp directory used to store download API-Extractor-generated doc models
-_doc-models
+# Dependencies
+/node_modules
 
-# Generated by build-api-nav during docs build.
-data/v*
-data/local
+# Production
+/build
 
-# Windows ADS files in docs.
-**/*:Zone.Identifier
+# Generated files
+.docusaurus
+.cache-loader
+.doc-models
+versions.json
 
-# Copy of versions json from data dir to redirect azure function
-api/fallback/versions.json
+# Generated API docs.
+# Note: keep `mdx` files that are handwritten
+docs/api/*
+!docs/api/**/*.mdx
+versioned_docs/*/api/*
+!versioned_docs/*/api/**/*.mdx
+
+# Test
+test-results
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*