build(docs): Update api-markdown-documenter and utilize new hierarchy options (microsoft#23504)

Update dev dependency on `@fluid-tools/api-markdown-documenter` and
leverage new "hierarchy" capabilities to move "folder" item documents
(packages and namespaces) _into_ their folders, renamed to `index`.

E.g., 
File structure before:

```
| fluid-framework.md
| fluid-framework
    | foo.md
    | ...
```

After:

```
| fluid-framework
    | index.md
    | foo.md
    | ...
```

This makes the breadcrumbs and navigation drop-downs generated by
docusaurus better match the intended hierarchy.

E.g.,

Namespace appearance in the nav before:

![image](https://github.com/user-attachments/assets/37fb8974-b306-4b37-a9df-2ec53052faf4)

- Note that there is a separate page and folder, and selecting the
folder doesn't navigate to the page; it just functions as a drop-down.

Namespace appearance after:

![image](https://github.com/user-attachments/assets/7ab5e37e-817b-495f-a569-8c00a2c360d6)

Breadcrumb before:

![image](https://github.com/user-attachments/assets/adba1322-f2a8-40a3-ad07-2d4b607ba918)

- Note that the parent folder isn't selectable, because Docusaurus
doesn't understand that it's supposed to point to the document of the
same name.

Breadcrumb after:

![image](https://github.com/user-attachments/assets/d74f49bb-62ba-4dcc-a5d1-dd8a3ec70539)

- Note that the parent entry is now selectable (screenshot was taken
with mouse hovering over item)


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

Author: Josmithr

docs/.gitignore

@@ -14,10 +14,11 @@ versions.json
 
 # Generated API docs.
 # Note: keep `mdx` files that are handwritten
-docs/api/*
-!docs/api/**/*.mdx
-versioned_docs/*/api/*
-!versioned_docs/*/api/**/*.mdx
+docs/api
+!docs/api/index.mdx
+versioned_docs/*/api
+!versioned_docs/*/api/index.mdx
+!versioned_docs/*/api/fluid-framework/index.mdx
 
 # Test
 test-results

docs/docs/api/index.mdx

@@ -6,13 +6,13 @@ sidebar_position: 10
 
 {/* Note: these contents are new and should be reviewed. The current website's API docs landing page has no description about what the packages do / when to use them. It's not very useful. */}
 
-To get started with the Fluid Framework, you'll want to take a dependency on our client library, [fluid-framework](./fluid-framework.md).
+To get started with the Fluid Framework, you'll want to take a dependency on our client library, [fluid-framework](./fluid-framework/index.md).
 
 You'll then want to pair that with the appropriate service client implementation based on your service.
 These include:
 
--   [@fluidframework/azure-client](./azure-client.md) (for use with [Azure Fluid Relay](../deployment/azure-fluid-relay.mdx))
--   [@fluidframework/odsp-client](./odsp-client.md) (for use with [SharePoint Embedded](../deployment/sharepoint-embedded.mdx))
--   [@fluidframework/tinylicious-client](./tinylicious-client.md) (for testing with [Tinylicious](../testing/tinylicious.mdx))
+-   [@fluidframework/azure-client](./azure-client/index.md) (for use with [Azure Fluid Relay](../deployment/azure-fluid-relay.mdx))
+-   [@fluidframework/odsp-client](./odsp-client/index.md) (for use with [SharePoint Embedded](../deployment/sharepoint-embedded.mdx))
+-   [@fluidframework/tinylicious-client](./tinylicious-client/index.md) (for testing with [Tinylicious](../testing/tinylicious.mdx))
 
 For more information on our service client implementations, see [Fluid Services](../deployment/service-options.mdx).

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

@@ -8,6 +8,7 @@ import {
 	ApiItemUtilities,
 	DocumentationNodeType,
 	getApiItemTransformationConfigurationWithDefaults,
+	HierarchyKind,
 	loadModel,
 	MarkdownRenderer,
 	ReleaseTag,
@@ -78,13 +79,42 @@ export async function renderApiDocumentation(inputDir, outputDir, uriRootDir, ap
 
 	const config = getApiItemTransformationConfigurationWithDefaults({
 		apiModel,
-		documentBoundaries: [
-			ApiItemKind.Class,
-			ApiItemKind.Enum,
-			ApiItemKind.Interface,
-			ApiItemKind.Namespace,
-			ApiItemKind.TypeAlias,
-		],
+		hierarchy: {
+			[ApiItemKind.Model]: HierarchyKind.Document,
+			[ApiItemKind.Namespace]: HierarchyKind.Folder,
+			[ApiItemKind.Package]: HierarchyKind.Folder,
+			getDocumentName: (apiItem, hierarchyConfig) => {
+				switch (apiItem.kind) {
+					case ApiItemKind.Model:
+						// We inject a custom landing page ("index.mdx") for a curated package reference.
+						// So we will give the auto-generated / complete model page its own separate document.
+						return "package-reference";
+
+					case ApiItemKind.Namespace:
+					case ApiItemKind.Package:
+						// Namespace and package items generate documents within their own folder.
+						return "index";
+					default:
+						let documentName = ApiItemUtilities.createQualifiedDocumentNameForApiItem(
+							apiItem,
+							hierarchyConfig,
+						);
+
+						// 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 (documentName.startsWith("_")) {
+							documentName = `u${documentName}`;
+						}
+
+						return documentName;
+				}
+			},
+		},
 		newlineKind: "lf",
 		uriRoot: uriRootDir,
 		includeBreadcrumb: false, // Docusaurus includes this by default based on file hierarchy
@@ -111,33 +141,6 @@ export async function renderApiDocumentation(inputDir, outputDir, uriRootDir, ap
 			}
 			return alerts;
 		},
-		getFileNameForItem: (apiItem) => {
-			switch (apiItem.kind) {
-				case ApiItemKind.Model: {
-					return "package-reference";
-				}
-				case ApiItemKind.Package: {
-					return ApiItemUtilities.getUnscopedPackageName(apiItem);
-				}
-				default: {
-					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;
-				}
-			}
-		},
 		skipPackage: (apiPackage) => {
 			const packageName = apiPackage.displayName;
 			const packageScope = PackageName.getScope(packageName);

docs/package.json

@@ -70,7 +70,7 @@
 		"@docusaurus/tsconfig": "^3.6.2",
 		"@docusaurus/types": "^3.6.2",
 		"@easyops-cn/docusaurus-search-local": "^0.45.0",
-		"@fluid-tools/api-markdown-documenter": "^0.17.2",
+		"@fluid-tools/api-markdown-documenter": "^0.18.0",
 		"@fluid-tools/markdown-magic": "file:../tools/markdown-magic",
 		"@fluidframework/build-common": "^2.0.3",
 		"@fluidframework/eslint-config-fluid": "^5.5.1",