refactor(docs): Add md/mdx linting via eslint and fix violations (mic…

…rosoft#23168)

Adds Markdown / MDX documentation linting via the following plugins:
- [eslint-mdx](https://github.com/mdx-js/eslint-mdx)
-
[@docusaurus/eslint-plugin](https://docusaurus.io/docs/api/misc/@docusaurus/eslint-plugin)

Also fixes violations in our docs.


[AB#21860](https://dev.azure.com/fluidframework/235294da-091d-4c29-84fc-cdfc3d90890b/_workitems/edit/21860)

.prettierignore

@@ -80,7 +80,8 @@ packages/framework/data-object-base/es5
 # Generated by policy-check
 packages/runtime/test-runtime-utils/src/assertionShortCodesMap.ts
 
-# TODO: Investigate formatting options that support JSX syntax in .mdx files
+# Prettier does not yet support mdx v3.
+# See <https://github.com/prettier/prettier/issues/12209>
 docs/**/*.mdx
 
 # Generated

docs/.eslintignore

@@ -0,0 +1,4 @@
+build
+node_modules
+docs/api
+versioned_docs/*/api

docs/.eslintrc.cjs

@@ -4,73 +4,96 @@
  */
 
 module.exports = {
-	extends: [require.resolve("@fluidframework/eslint-config-fluid"), "prettier"],
 	parserOptions: {
-		project: ["./tsconfig.json"],
+		ecmaVersion: "2022",
 	},
-	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"],
+	overrides: [
+		// Rules for code
+		{
+			files: ["src/**/*.{ts,tsx}", "test/**/*.{ts,tsx}"],
+			extends: [require.resolve("@fluidframework/eslint-config-fluid"), "prettier"],
+			parserOptions: {
+				project: ["./tsconfig.json"],
 			},
-		],
-
-		"import/no-internal-modules": [
-			"error",
-			{
-				allow: ["@docusaurus/**", "@site/**", "@theme/**"],
+			settings: {
+				react: {
+					version: "detect",
+				},
 			},
-		],
+			rules: {
+				// Required by Docusaurus for certain component exports.
+				"import/no-default-export": "off",
 
-		"import/no-unresolved": [
-			"error",
-			{
-				ignore: ["^@docusaurus/", "^@theme/", "^@theme-original/"],
-			},
-		],
+				"import/no-unassigned-import": [
+					"error",
+					{
+						// Allow unassigned imports of css files.
+						allow: ["**/*.css"],
+					},
+				],
 
-		// All dependencies in this package are dev
-		"import/no-extraneous-dependencies": [
-			"error",
-			{
-				devDependencies: true,
-			},
-		],
+				"import/no-internal-modules": [
+					"error",
+					{
+						allow: ["@docusaurus/**", "@site/**", "@theme/**"],
+					},
+				],
 
-		// 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"],
+				"import/no-unresolved": [
+					"error",
+					{
+						ignore: ["^@docusaurus/", "^@theme/", "^@theme-original/"],
+					},
+				],
+
+				// All dependencies in this package are dev
+				"import/no-extraneous-dependencies": [
+					"error",
+					{
+						devDependencies: true,
+					},
+				],
+
+				// 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 file rule overrides
+					files: ["test/**/*"],
+					parserOptions: {
+						project: ["./test/tsconfig.json"],
+					},
+				},
+				{
+					// Config file tool overrides
+					files: ["docusaurus.config.ts", "playwright.config.ts", "infra/**/*"],
+					rules: {
+						"import/no-internal-modules": "off",
+					},
+				},
+			],
 		},
+
+		// Rules for .md/.mdx documents
 		{
-			// Config files
-			files: ["docusaurus.config.ts", "playwright.config.ts", "infra/**/*"],
+			files: ["**/*.md", "**/*.mdx"],
+			// TODO: extend prettier plugin, once prettier supports MDX v3.
+			// See <https://github.com/prettier/prettier/issues/12209>
+			extends: ["plugin:mdx/recommended"],
+			plugins: ["@docusaurus/eslint-plugin"],
 			rules: {
-				"import/no-internal-modules": "off",
-				"import/no-nodejs-modules": "off",
-				"unicorn/no-process-exit": "off",
+				// See <https://docusaurus.io/docs/api/misc/@docusaurus/eslint-plugin/no-html-links>
+				"@docusaurus/no-html-links": "error",
+
+				// See <https://docusaurus.io/docs/api/misc/@docusaurus/eslint-plugin/prefer-docusaurus-heading>
+				"@docusaurus/prefer-docusaurus-heading": "error",
 			},
 		},
 	],

docs/README.md

@@ -137,6 +137,25 @@ The replacement syntax to use in `.mdx` files would be:
 
 (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 `{#<id>}` 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: <https://github.com/facebook/docusaurus/issues/9155>.
+
 ### Mermaid
 
 Docusaurus has built-in support for [mermaid](https://mermaid.js.org/) diagrams.
@@ -182,7 +201,6 @@ The following npm scripts are supported in this directory:
 | Script | Description |
 |--------|-------------|
 | `build` | Build everything: the API documentation, the website, the tests, etc. |
-| `prebuild:api-documentation` | Temporary workaround for AB#24394. Cleans up existing generated API documentation before generating new content. |
 | `build:api-documentation` | Download API model artifacts and generate API documentation. |
 | `prebuild:docusaurus` | Runs pre-site build metadata generation. |
 | `build:docusaurus` | Build the website with Docusaurus. |

docs/docs/build/releases-and-apitags.mdx

@@ -32,7 +32,7 @@ There are no guarantees for API breakages or Fluid document compatibility among
 These are done on demand to preview new APIs or try fixes for our partners. They are represented by the `dev` tag in npm
 There are no guarantees for API breakages or Fluid document compatibility among the release changes. Assume you will have to throw away containers generated by older release candidates
 
-## API Support Levels {#api-support-levels}
+## API Support Levels \{#api-support-levels}
 
 For packages that are part of the `@fluidframework` scope and the `fluid-framework` package, we use import paths to communicate the stability and guarantees associated with those APIs.
 

docs/docs/glossary.mdx

@@ -34,7 +34,7 @@ A Fluid container can be _attached_ or _detached_. A detached container is not c
 be loaded by other clients. Newly created containers begin in a detached state, which allows developers to add initial
 data if needed before attaching the container. Also see [Attached](#attached).
 
-## Distributed data structures (DDSes) {#distributed-data-structures}
+## Distributed data structures (DDSes) \{#distributed-data-structures}
 
 DDSes are the data structures Fluid Framework provides for storing collaborative data. As collaborators modify the data,
 the changes will be reflected to all other collaborators.

docs/docs/testing/telemetry.mdx

@@ -14,7 +14,7 @@ your other telemetry, and route the event data in whatever way you need.
 The `ITelemetryBaseLogger` is an interface within the `@fluidframework/common-definitions` package. This interface can
 be implemented and passed into the service client's constructor via the `props` parameter.
 
-All Fluid service clients (for example, [AzureClient][]) and [TinyliciousClient][])) allow passing a `logger?: ITelemetryBaseLogger`
+All Fluid service clients (for example, [AzureClient][] and [TinyliciousClient][]) allow passing a `logger?: ITelemetryBaseLogger`
 into the service client props. Both `createContainer()` and `getContainer()` methods will then create an instance of the `logger`.
 
 `TinyliciousClientProps` interface definition takes an optional parameter `logger`.
@@ -155,7 +155,7 @@ The Fluid Framework sends events in the following categories:
 
 ### EventName
 
-This property contains a unique name for the event. The name may be namespaced, delimitted by a colon ':'.
+This property contains a unique name for the event. The name may be namespaced, delimited by a colon ':'.
 Additionally, some event names (not the namespaces) contain underscores '\_', as a free-form subdivision of
 events into different related cases. Once common example is `foo_start`, `foo_end` and `foo_cancel` for
 performance events.
@@ -263,15 +263,15 @@ async function start(): Promise<void> {
       const id = await container.attach();
       location.hash = id;
   }
+}
 ```
 
 Now, whenever a telemetry event is encountered, the custom `send()` method gets called and will print out the entire
 event object.
 
 <img
 	src="https://storage.fluidframework.com/static/images/consoleLogger_telemetry_in_action.png"
-	alt="The
-  ConsoleLogger sends telemetry events to the browser console for display."
+	alt="The ConsoleLogger sends telemetry events to the browser console for display."
 />
 
 :::warning

docs/docs/testing/typed-telemetry.mdx

@@ -143,7 +143,7 @@ startTelemetry(telemetryConfig);
 
 You can now run the app and see the telemetry being printed on your console.
 
-### Interpreting telemetry data {#telemetry_visualization}
+### Interpreting telemetry data \{#telemetry_visualization}
 
 This section provides a set of Azure App Insights queries related to collaborative sessions within a Fluid Framework application. It is intended to be used with the telemetry generated from @fluidframework/fluid-telemetry package whose integration steps are outline above.
 

docs/package.json

@@ -28,8 +28,8 @@
 		"clean:test": "rimraf --glob test-results",
 		"clean:versions-json": "rimraf --glob ./versions.json",
 		"download-doc-models": "node ./infra/download-doc-models.mjs",
-		"eslint": "eslint src test --format stylish",
-		"eslint:fix": "eslint src test --format stylish --fix",
+		"eslint": "eslint . --format stylish",
+		"eslint:fix": "eslint . --format stylish --fix",
 		"format": "npm run prettier:fix",
 		"generate-api-documentation": "dotenv -- node ./infra/generate-api-documentation.mjs",
 		"generate-versions": "dotenv -- node ./infra/generate-versions.mjs",
@@ -61,6 +61,7 @@
 	"devDependencies": {
 		"@azure/static-web-apps-cli": "^2.0.1",
 		"@docusaurus/core": "^3.6.2",
+		"@docusaurus/eslint-plugin": "^3.6.2",
 		"@docusaurus/module-type-aliases": "^3.6.2",
 		"@docusaurus/plugin-content-docs": "^3.6.2",
 		"@docusaurus/preset-classic": "^3.6.2",
@@ -85,6 +86,8 @@
 		"dotenv-cli": "^7.4.3",
 		"eslint": "~8.55.0",
 		"eslint-config-prettier": "~9.1.0",
+		"eslint-mdx": "^3.1.5",
+		"eslint-plugin-mdx": "^3.1.5",
 		"fs-extra": "^11.2.0",
 		"linkcheck-bin": "3.0.0-1",
 		"lunr": "^2.3.9",