# Website This directory contains the code and content for . The website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator. ## Dependency installation The Fluid Framework repository uses [pnpm](https://pnpm.io/) for dependency management. If you don't have `pnpm` installed, you will need to do so first. ```shell pnpm i ``` ## DOMPurify browser script `static/dompurify/purify.min.js` is a checked-in copy of DOMPurify's browser distribution. Its source is `dist/purify.min.js` in the official `dompurify` npm package. The website build does not generate this file. `docusaurus.config.ts` loads this script before `static/trusted-types-policy.js`. The Trusted Types policy uses `DOMPurify.sanitize` to sanitize HTML. The website serves this checked-in file directly. Updating the dependency in `package.json` does not update the script that browsers receive. ### Update DOMPurify Keep the package dependency, lockfile, and checked-in browser script consistent. 1. Update the `dompurify` dependency to the selected version. 2. Regenerate `pnpm-lock.yaml` with pnpm. 3. Confirm the installed version and the lockfile resolution. 4. Copy `dist/purify.min.js` from that installed package into `static/dompurify/purify.min.js`. 5. Preserve the upstream license notice and apply the repository's formatting. 6. Build the website and check navigation, search, HTML sanitization, and Mermaid diagrams. For example, from the `website` directory, copy and format the installed distribution with PowerShell: ```powershell Copy-Item .\node_modules\dompurify\dist\purify.min.js .\static\dompurify\purify.min.js pnpm exec prettier --write .\static\dompurify\purify.min.js ``` Do not manually modify DOMPurify's implementation. The update to 3.4.15 changed `package.json`, regenerated `pnpm-lock.yaml`, and replaced the checked-in browser distribution. The lockfile resolves both the direct dependency and Mermaid's DOMPurify dependency to 3.4.15. TODO: AB#84053 - Investigate using the installed DOMPurify dependency directly instead of maintaining a checked-in copy. Preserve its load order before the Trusted Types policy. This follow-up does not block dependency updates. ## Local Development There are two options for local testing. ### `build:generate-content` and `start` The easiest way to get started testing the website is to leverage Docusaurus's `start` functionality. This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. Before you can use this, you'll need to ensure our API documentation has been built. So start by running: ```shell npm run build:generate-content ``` Then, run: ```shell npm start ``` #### Search The website search index is generated by [Pagefind](https://pagefind.app/) after Docusaurus builds the static site. To test search locally, build and serve the website: ```shell pnpm run build pnpm run serve ``` Note: the Docusaurus build is fairly slow. If you don't need to test search, it is recommended to run `pnpm run start` instead. This is faster, and will watch for content changes and update automatically. You will still need to build the API documentation first. ### Local API docs build To include repo-local API documentation when building the site locally, you will first need to do the following: 1. Build the code from the root of the repo. 2. Create a `.env` file in this directory with the following contents: ``` LOCAL_API_DOCS=true ``` So long as the `LOCAL_API_DOCS` environment variable is set to `true`, local API documentation will be included when building the site. To remove the local API docs, simply remove the above variable or set it to `false`, `npm run clean` and rebuild as needed. ## Testing The website has two complementary test suites: - **Unit tests** use [Vitest](https://vitest.dev/) and live under `test/unit`. Use these for isolated components, utilities, data transformations, and error handling that do not require a browser or a complete website build. Unit tests should generally be preferred when either test flavor can cover the behavior because they run quickly and make failures easier to diagnose. - **Site tests** use [Playwright](https://playwright.dev/) and live under `test/site-tests`. Use these for browser-visible behavior, navigation, accessibility, layout, search, and workflows that cross component or page boundaries. Playwright serves the previously built static site, so run `pnpm run build:site` before running site tests when the build output is not current. Run only the unit tests with: ```shell pnpm run test:unit ``` Run only the site tests with: ```shell pnpm run test:site ``` Run both suites with: ```shell pnpm test ``` The aggregate command installs Playwright's browser dependencies before running the suites. `pnpm run build:test` type-checks all test code without executing it. ## Deployment The Fluid Framework website is deployed using the build-docs pipeline. `INSTRUMENTATION_KEY` is set as a pipeline variable here. ## Writing site documentation For details about authoring documentation content in Docusaurus, see [here](https://docusaurus.io/docs/create-doc). ### File organization ``` |--- docs (Current version documentation) |--- versioned_docs (previous and future version documentation) | |---version-x (version *x* documentation) | |---version-local (special directory in which repo-local API docs are generated and can be previewed when building the site locally) |--- src | |--- components (React components available to other site documents, pages, and components) | |--- css (CSS modules available to other site documents, pages, and components) | |--- pages (Unversioned site contents) | |--- theme (Theme component / page overrides) ``` ### MDX MDX syntax (supported by Docusaurus) is powerful. But there is a subset of standard Markdown syntax that is not supported. For example, any HTML-like syntax will _always_ be treated as JSX syntax, so standard embedded HTML patterns don't work. Most of the time, this isn't an issue, since substituting JSX syntax is generally fine. With some exceptions. #### Leveraging React components For an overview of how to leverage React components in MDX documentation, see [here](https://docusaurus.io/docs/markdown-features/react). ##### Adding React components React components should be saved under `src/components/...`. They can be imported in other components, pages, and documents via `@site/src/components/...`. ##### Linking to API documentation Use `PackageLink` and `ApiLink` to link to generated API documentation from an MDX document. These components select the API documentation for the active documentation version. Import the components that the document uses: ```tsx import { ApiLink, PackageLink } from "@site/src/components/shortLinks"; ``` Use the unscoped package name with both components. Use a TSDoc declaration reference for the `api` value of `ApiLink`: ```mdx See and . ``` Add `newApi` when the current published API model does not contain a new package or API. The component renders its content as inline code until the target exists. The component writes a build debug message when it renders inline code. When the target exists, the component renders a link. `newApi` can be removed once the target exists. ```mdx ``` The `newApi` shorthand is equivalent to `newApi={true}`. Invalid references and ambiguous references remain build errors. Use a TSDoc selector to resolve an ambiguous API kind, such as `(NewApi:class)` or `(NewApi:interface)`. For an API rename, set `api` to an object with `previous` and `new` declaration references: ```mdx ``` The component tries `new` first. It uses `previous` while the published model contains only the old API. When child content is omitted, the component displays the name of the API that resolves. ```mdx ``` For a package rename, set `package` to an object with `previous` and `new` names: ```mdx ``` The component uses `previous` while the published model contains only the old package. ```mdx ``` All transition modes permit explicit rich child content. The component preserves the child content when it renders a link or inline code: ```mdx **New API** ``` #### Comments A common pattern for adding inline comments in `.md` files looks like: ```md ``` The replacement syntax to use in `.mdx` files would be: ```mdx {/* I am a comment */} ``` (just like you would do in a JSX context!) #### Custom Heading IDs In GitHub-flavored Markdown, you can assign a custom anchor ID to a heading by appending `{#}` to the heading text. E.g., ```markdown # Foo {#bar} ``` Because curly braces are interpreted specially by JSX, this syntax doesn't work as is in `.mdx` documents. Instead, you'll need to escape the opening brace to prevent MDX from attempting to process the syntax as JSX. E.g., ```markdown # Foo \{#bar} ``` See the following Docusaurus issue for more context: . ### Mermaid Docusaurus has built-in support for [mermaid](https://mermaid.js.org/) diagrams. We recommend leveraging these when possible over alternatives (ascii art, binary image files, SVG, etc.). Rationale: - Docusaurus will ensure consistent styling - Non-binary source, directly in the document. For more details about leveraging Mermaid diagrams in Docusaurus, see [here](https://docusaurus.io/docs/markdown-features/diagrams). ### Documents vs Pages _Documents_ and _Pages_ are distinct concepts in Docusaurus. For an overview of each, see: [Documents](https://docusaurus.io/docs/docs-introduction) and [Pages](https://docusaurus.io/docs/creating-pages). Some primary distinctions: 1. _Documents_ live under `docs` and `versioned_docs`. _Pages_ live under `src/pages`. 1. _Documents_ are versioned. _Pages_ are not. ### The Sidebar For an overview of how to configure sidebars in Docusaurus, see [here](https://docusaurus.io/docs/sidebar). The site's "current" version sidebar is configured via `sidebars.ts`. Sidebars for other versions are configured via `versioned_sidebars/version-.json`. - Versioned sidebars do not yet support JS/TS file formats. See . Note that sidebars are configured for documents under `docs` and `versioned_docs`; they do not apply to unversioned _Pages_. ### Documentation Versioning For an overview of Docusaurus's versioning functionality, see [here](https://docusaurus.io/docs/versioning). We currently offer versioned documentation for each of our supported major versions. This documentation is intended to be kept up-to-date with the most recent release of each major version series. For now, this means we publish documentation (including generated API documentation) for versions `1.x`, `2.x`, and `3.x`. - We also support generating API documentation for the local repo code in local development only. See [Local API docs build](#local-api-docs-build), but these are not intended to be published. #### Why Only Major Versions? We aim to keep the number of concurrently maintained site versions minimized, for a number of reasons: 1. Developer overhead - the more versions of the docs we offer, the more work we take on to keep documentation for supported versions up to date. 2. User overhead - the more versions we offer, the more users have to think about when they engage with our website. 3. Build performance - Docusaurus's build isn't fast. The more versions we add to our suite, the longer our build times become. #### Updating the Site Version These steps are based on Docusaurus's tutorial [here](https://docusaurus.io/docs/versioning#tutorials). Note: generating the API documentation for the new "current" version will fail if the release branch for that version has not yet been created. 1. Run `npx --no-install docusaurus docs:version ` from the root of this directory. E.g., `... docusaurus docs:version 2` when prepping for `v3` documentation. - This will copy the contents of `docs` into `versioned_docs` under the specified version ID. - This will also generate a sidebar configuration for the copied version under `versioned_sidebars`. 1. Update `config/docs-versions.mjs` to update the version ID for the "current" version, and add the newly frozen version to the `otherVersions` list. This will automatically update aspects of the site, including: 1. Which versions of the API documentation are generated during the build 1. The version selection drop-down in the site header ### Best practices #### Markdown ##### Links As a general rule, links between documents on the site should: - Use relative file paths - Enhances the IDE experience. - Gives us better / earlier broken link detection. - Specify the `.md`/`.mdx` file extension - Docusaurus applies a different resolution strategy for relative _file path_ links than it does for URL links. See: **Avoid** using fully qualified URLs (e.g., `[foo](https://fluidframework.com/docs/foo)`). - Docusaurus will treat such links as _external_, which will result in new windows/tabs being opened in the user's browser when clicked. **Avoid** using _absolute_ document paths relative to the site root (e.g., `[foo](/docs/foo.mdx)`) - While these work just fine as far as Docusaurus is concerned, they break the ability to navigate through links in an IDE. #### Assets ##### Images When adding image assets for use in the website, please follow the [image upload instructions](../docs/content/Contributing/Working-with-the-Website/Uploading-Images-for-the-Website.md). Namely, avoid adding binary files like images to the GitHub repo. Instead, upload them to our Azure blob storage, and reference by URL. E.g., Images may only be uploaded by Microsoft Fluid team members. If you do not have the appropriate permissions, but would like to contribute to our documentation, please reach out to us [here](https://github.com/microsoft/FluidFramework/issues/new/choose). ##### YouTube Videos To meet our privacy requirements, it is important that we avoid embedding content that will collect cookies. To ensure this, please never embed YouTube videos using their standard embed format. Instead, be sure to leverage `https://www.youtube-nocookie.com/`. To make this easy, we have a `YoutubeVideo` component under `@site/src/components/youtubeVideo` that can be used to embed a specified video ID using the correct settings. Example: ```mdx import { YoutubeVideo } from "@site/src/components/youtubeVideo"; ... ``` ## Scripts The following npm scripts are supported in this directory: | Script Name | Script Body | Description | | - | - | - | | `build` | `concurrently npm:build:site npm:build:test` | Build everything: the API documentation, the website, the tests, etc. | | `build:api-documentation` | `npm run download-doc-models && npm run generate-api-documentation` | Download API model artifacts and generate API documentation. | | `prebuild:docusaurus` | `npm run generate-versions` | Runs pre-site build metadata generation. | | `build:docusaurus` | `cross-env NODE_OPTIONS=--max-old-space-size=8192 docusaurus build` | Build the website with Docusaurus. Note that 3 documentation suite versions taxes Docusaurus and causes it to run out of memory. The default heap limit is increased to accommodate this. | | `build:generate-content` | `concurrently npm:build:markdown-magic npm:build:api-documentation` | Generate site content. Includes API documentation, as well as content generated / embedded by `markdown-magic`. | | `build:markdown-magic` | `markdown-magic` | Run `markdown-magic` to generate / embed contents in Markdown files. | | `build:search` | `pagefind --site build` | | | `build:site` | `npm run build:generate-content && npm run build:docusaurus && npm run build:search` | Build the site, including API documentation. | | `build:test` | `tsc --project test/tsconfig.json --pretty --noEmit` | TSC build of the test code as a sanity check. | | `check-links` | `linkcheck http://127.0.0.1:3000 --skip-file skipped-urls.txt` | Run link validation on the website. Requires the website to be running locally, either via `start` or `serve`. | | `ci:check-links` | `start-server-and-test "npm run serve -- --host 127.0.0.1 --no-open" http://127.0.0.1:3000 check-links` | `check-links` variant for CI. Serves the site before running checks. | | `clean` | `concurrently "npm:clean:*"` | Clean up generated artifacts (build output, etc.). | | `clean:api-documentation` | `node ./infra/clean-api-documentation.mjs` | Clean up generate API documentation content. | | `clean:doc-models` | `rimraf --glob .doc-models` | Clean up downloaded API model artifacts. | | `clean:docusaurus` | `docusaurus clear` | Run Docusaurus's "clean". | | `clean:test` | `rimraf --glob test-results` | Clean up generated test output | | `clean:versions-json` | `rimraf --glob ./versions.json` | Clean up generated `versions.json` file. | | `download-doc-models` | `node ./infra/download-doc-models.mjs` | Download API model artifacts published from our release branches. | | `eslint` | `eslint . --format stylish` | Run `eslint`. | | `eslint:fix` | `eslint . --format stylish --fix` | Run `eslint` with auto-fix enabled. | | `format` | `npm run prettier:fix` | Fix formatting issues with `prettier`. | | `generate-api-documentation` | `dotenv -- node ./infra/generate-api-documentation.mjs` | Generate API documentation from downloaded API model artifacts. | | `generate-versions` | `dotenv -- node ./infra/generate-versions.mjs` | | | `preinstall` | `node ../scripts/only-pnpm.cjs` | Ensure developer is using `pnpm`. | | `install-no-frozen` | `node ../scripts/install-no-frozen.cjs` | | | `lint` | `concurrently npm:eslint npm:prettier` | Check for linter violations. | | `lint:fix` | `npm run eslint:fix && npm run prettier:fix` | Auto-fix linter violations. | | `prettier` | `prettier --check . --cache --ignore-path ../.prettierignore` | Check for formatting issues with `prettier`. | | `prettier:fix` | `prettier --write . --cache --ignore-path ../.prettierignore` | Fix formatting issues with `prettier`. | | `rebuild` | `npm run clean && npm run build` | Clean up existing generated artifacts and re-run the build. | | `serve` | `docusaurus serve` | Serves the built website using Docusaurus. | | `serve-with-azure-emulation` | `swa start --config-name ff-doc-site` | Serves the built website using Docusaurus, including Azure service emulation for our Azure functions. | | `prestart` | `npm run generate-versions` | Runs pre-site build metadata generation. | | `start` | `docusaurus start` | Runs the website in watch mode with Docusaurus. | | `pretest` | `playwright install --with-deps` | Install necessary `playwright` dependencies before running tests. | | `test` | `npm run test:unit && npm run test:site` | Run all tests (`playwright` UX tests and `vitest` unit tests) | | `test:site` | `playwright test` | Run UX tests using `playwright` | | `test:unit` | `vitest run` | Run unit tests using `vitest` |