build(docs): Ensure API docs gen doesn't create "partial" documents (#23147)

Docusaurus treats document files whose names start with `_` as "partial"
documents, which don't get included in site output. We have a couple of
API exports that start with `_`, and result in files that end up treated
as partials. To work around this, we now prepend "u" to any files that
would otherwise start with an underscore.

"u" is a pretty arbitrary choice. We can't simply remove the underscore,
as that would be much more likely to create filename collisions. While
it is technically possible that we could export an API item that starts
with "u_", doing so would violate our naming conventions, and seems
pretty unlikely. If such an API item is added, Docusaurus will start
failing on duplicate routes, at which point we can change strategies.

See https://docusaurus.io/docs/create-doc for more details on partial
documents.


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

Author: Josmithr

docs/docusaurus.config.ts

@@ -57,9 +57,8 @@ const config: Config = {
 	// For GitHub pages deployment, it is often '/<projectName>/'
 	baseUrl: "/",
 
-	// Reports many false positives for API documentation
-	onBrokenAnchors: "ignore",
-	onBrokenLinks: "warn", // TODO:AB#23443: Set to "throw" once violations have been fixed.
+	onBrokenAnchors: "throw",
+	onBrokenLinks: "throw",
 	onBrokenMarkdownLinks: "throw",
 	onDuplicateRoutes: "throw",
 

docs/infra/api-markdown-documenter/render-api-documentation.mjs

@@ -123,7 +123,21 @@ export async function renderApiDocumentation(inputDir, outputDir, uriRootDir, ap
 					return ApiItemUtilities.getUnscopedPackageName(apiItem);
 				}
 				default: {
-					return ApiItemUtilities.getQualifiedApiItemName(apiItem);
+					const qualifiedName = ApiItemUtilities.getQualifiedApiItemName(apiItem);
+					let fileName = qualifiedName;
+
+					// Docusaurus treats any document name starting with "_" as a "partial" document, which
+					// will not be included in the site output.
+					// See: <https://docusaurus.io/docs/create-doc>
+					// To work around this, while (hopefully) preventing name collisions, we will prefix
+					// The filename with "u". E.g. `_foo.md` -> `u_foo.md`.
+					// This doesn't affect displayed contents, strictly changes the resulting filenames and any
+					// links to them.
+					if (qualifiedName.startsWith("_")) {
+						fileName = `u${qualifiedName}`;
+					}
+
+					return fileName;
 				}
 			}
 		},
@@ -169,7 +183,6 @@ export async function renderApiDocumentation(inputDir, outputDir, uriRootDir, ap
 
 			// #endregion
 
-			// TODO: custom landing pages for API suites?
 			let fileContents;
 			try {
 				const documentBody = MarkdownRenderer.renderDocument(document, {
@@ -189,7 +202,7 @@ export async function renderApiDocumentation(inputDir, outputDir, uriRootDir, ap
 				);
 			}
 
-			let filePath = path.join(outputDir, `${document.documentPath}.md`);
+			const filePath = path.join(outputDir, `${document.documentPath}.md`);
 
 			try {
 				await fs.ensureFile(filePath);

docs/skipped-urls.txt

@@ -33,9 +33,3 @@ https://foo-my.sharepoint.com*
 
 # Docusaurus infra
 http://localhost:3000/assets/css/styles.*.css
-
-# TODO:AB#23443: Docusaurus ignores doc files whose names begin with "_".
-# See https://docusaurus.io/docs/create-doc
-# We need to update our API docs build configuration to not emit files starting with "_"s.
-http://localhost:3000/docs/api/fluid-framework/internaltypes/_inlinetrick-typealias
-http://localhost:3000/docs/api/tree/internaltypes/_inlinetrick-typealias