build(docs): Update api-markdown-documenter to 0.21.0

docs/infra/api-markdown-documenter/admonition-node.mjs

@@ -5,13 +5,15 @@
 
 //@ts-check
 /** @typedef {import("@fluid-tools/api-markdown-documenter").BlockContent} BlockContent */
+/** @typedef {import("@fluid-tools/api-markdown-documenter").ToMarkdownContext} ToMarkdownContext */
+/** @typedef {import("mdast").BlockContent} MdastBlockContent */
+/** @typedef {import("mdast").PhrasingContent} MdastPhrasingContent */
+/** @typedef {"note" | "tip" | "info" | "warning" | "danger"} AdmonitionKind */
 
-import { DocumentationParentNodeBase } from "@fluid-tools/api-markdown-documenter";
-
-/**
- * The {@link @fluid-tools/api-markdown-documenter#DocumentationNode."type"} of {@link AdmonitionNode}.
- */
-export const admonitionNodeType = "Admonition";
+import {
+	blockContentToMarkdown,
+	DocumentationParentNodeBase,
+} from "@fluid-tools/api-markdown-documenter";
 
 /**
  * A block of content representing a notice that should be highlighted for the user.
@@ -48,15 +50,57 @@ export const admonitionNodeType = "Admonition";
 export class AdmonitionNode extends DocumentationParentNodeBase {
 	/**
 	 * @param {BlockContent[]} children - Child node content.
-	 * @param {string} admonitionKind - The kind of admonition. See {@link https://docusaurus.io/docs/markdown-features/admonitions}.
+	 * @param {AdmonitionKind} admonitionKind - The kind of admonition. See {@link https://docusaurus.io/docs/markdown-features/admonitions}.
 	 * @param {string | undefined} title - (Optional) Title text for the admonition.
 	 */
 	constructor(children, admonitionKind, title) {
 		super(children);
 
-		this.type = admonitionNodeType;
+		this.type = "admonition";
 
 		this.admonitionKind = admonitionKind;
 		this.title = title;
 	}
+
+	/**
+	 * Generates Markdown representing a Docusaurus Admonition.
+	 *
+	 * @param {ToMarkdownContext} context - The transformation context.
+	 *
+	 * @returns {MdastBlockContent[]} The Markdown AST representing the admonition.
+	 */
+	toMarkdown(context) {
+		/**
+		 * @type {MdastBlockContent[]}
+		 */
+		const transformedChildren = [];
+		for (const child of this.children) {
+			// @ts-ignore -- Limitation of using types in JavaScript: we can't explicitly mark `AdmonitionNode` as only containing phrasing content.
+			transformedChildren.push(...blockContentToMarkdown(child, context));
+		}
+
+		// If the admonition has a title, prepend it to the list of children with the `directiveLabel` property set.
+		if (this.title !== undefined) {
+			transformedChildren.unshift({
+				type: "paragraph",
+				data: {
+					directiveLabel: true,
+				},
+				children: [
+					{
+						type: "text",
+						value: this.title,
+					},
+				],
+			});
+		}
+
+		return [
+			{
+				type: "containerDirective",
+				name: this.admonitionKind,
+				children: transformedChildren,
+			},
+		];
+	}
 }

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

@@ -6,6 +6,7 @@
 //@ts-check
 /** @typedef {import("@fluid-tools/api-markdown-documenter").ApiItem} ApiItem */
 /** @typedef {import("@fluid-tools/api-markdown-documenter").ApiItemTransformationConfiguration} ApiItemTransformationConfiguration */
+/** @typedef {import("@fluid-tools/api-markdown-documenter").BlockContent} BlockContent */
 /** @typedef {import("@fluid-tools/api-markdown-documenter").DocumentationNode} DocumentationNode */
 
 import {
@@ -14,12 +15,11 @@ import {
 	CodeSpanNode,
 	HeadingNode,
 	LayoutUtilities,
-	LineBreakNode,
 	LinkNode,
+	ParagraphNode,
 	PlainTextNode,
 	ReleaseTag,
 	SectionNode,
-	SpanNode,
 	transformTsdoc,
 } from "@fluid-tools/api-markdown-documenter";
 
@@ -28,9 +28,9 @@ import { AdmonitionNode } from "./admonition-node.mjs";
 const customExamplesSectionTitle = "Usage";
 const customThrowsSectionTitle = "Error Handling";
 
-const supportDocsLinkSpan = new SpanNode([
+const supportDocsLinkParagraph = new ParagraphNode([
 	new PlainTextNode("For more information about our API support guarantees, see "),
-	LinkNode.createFromPlainText(
+	new LinkNode(
 		"here",
 		// Is there a URL that would be relative to the current site? (For development use)
 		"https://fluidframework.com/docs/build/releases-and-apitags/#api-support-levels",
@@ -42,7 +42,7 @@ const supportDocsLinkSpan = new SpanNode([
  * A special use notice for the "@system" tag.
  */
 const systemNotice = new AdmonitionNode(
-	[supportDocsLinkSpan],
+	[supportDocsLinkParagraph],
 	/* admonitionKind: */ "warning",
 	"This API is reserved for internal system use and should not be imported directly. It may change at any time without notice.",
 );
@@ -52,7 +52,7 @@ const systemNotice = new AdmonitionNode(
  */
 const sealedNotice = new AdmonitionNode(
 	[
-		new SpanNode([
+		new ParagraphNode([
 			new PlainTextNode(
 				'This type is "sealed," meaning that code outside of the library defining it should not implement or extend it. Future versions of this type may add members or make typing of readonly members more specific.',
 			),
@@ -67,7 +67,7 @@ const sealedNotice = new AdmonitionNode(
  */
 const inputNotice = new AdmonitionNode(
 	[
-		new SpanNode([
+		new ParagraphNode([
 			new PlainTextNode(
 				'This type is "input," meaning that code outside of the library defining it should not read from it. Future versions of this type may add optional members or make typing of members more general.',
 			),
@@ -105,19 +105,18 @@ function createSupportNotice(apiItem, isImportable) {
 	 * @param {string} admonitionTitle - Title to display for the admonition.
 	 */
 	function createAdmonition(importSubpath, admonitionTitle) {
-		/** @type {DocumentationNode[]} */
+		/** @type {BlockContent[]} */
 		const admonitionChildren = [];
 		if (isImportable) {
 			admonitionChildren.push(
-				new SpanNode([
+				new ParagraphNode([
 					new PlainTextNode("To use, import via "),
 					CodeSpanNode.createFromPlainText(`${packageName}/${importSubpath}`),
 					new PlainTextNode("."),
 				]),
-				LineBreakNode.Singleton,
 			);
 		}
-		admonitionChildren.push(supportDocsLinkSpan);
+		admonitionChildren.push(supportDocsLinkParagraph);
 		return new AdmonitionNode(
 			admonitionChildren,
 			/* admonitionKind: */ "warning",
@@ -305,7 +304,7 @@ function createDeprecationNoticeSection(apiItem, config) {
 
 	return new AdmonitionNode(
 		transformedDeprecatedBlockContents,
-		"Warning",
+		"warning",
 		"This API is deprecated and will be removed in a future release.",
 	);
 }

docs/infra/api-markdown-documenter/custom-transformations.mjs

@@ -0,0 +1,72 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+//@ts-check
+/** @typedef {import("@fluid-tools/api-markdown-documenter").BlockContent} BlockContent */
+/** @typedef {import("@fluid-tools/api-markdown-documenter").ToMarkdownContext} ToMarkdownContext */
+/** @typedef {import("mdast").BlockContent} MdastBlockContent */
+/** @typedef {import("mdast").RootContent} MdastRootContent */
+
+import {
+	documentationNodeToHtml,
+	HtmlRenderer,
+	TableNode,
+} from "@fluid-tools/api-markdown-documenter";
+import { AdmonitionNode } from "./admonition-node.mjs";
+
+/**
+ * Generates Markdown for an {@link AdmonitionNode} using Docusaurus syntax.
+ *
+ * @param {AdmonitionNode} admonitionNode - The node to render.
+ * @param {ToMarkdownContext} context - The transformation context.
+ *
+ * @type {import("@fluid-tools/api-markdown-documenter").ToMarkdownTransformation<AdmonitionNode, MdastBlockContent[]>}
+ */
+export const transformAdmonitionNode = (admonitionNode, context) => {
+	return admonitionNode.toMarkdown(context);
+};
+
+/**
+ * Type guard for element HAST nodes.
+ * @param {import("hast").Nodes} node - The node to check.
+ * @returns {node is import("hast").Element} Whether the node is an element.
+ */
+function isElement(node) {
+	return node.type === "element";
+}
+
+/**
+ * Renders a {@link TableNode} using HTML syntax, and applies the desired CSS class to it.
+ *
+ * @param {TableNode} tableNode - The node to render.
+ * @param {ToMarkdownContext} context - The transformation context.
+ *
+ * @type {import("@fluid-tools/api-markdown-documenter").ToMarkdownTransformation<TableNode, [MdastBlockContent]>}
+ */
+export const transformTableNode = (tableNode, context) => {
+	// Generate HTML AST for the table node.
+
+	const htmlTree = documentationNodeToHtml(tableNode, {
+		startingHeadingLevel: context.headingLevel,
+		logger: context.logger,
+		customTransformations: undefined,
+	});
+
+	if (!isElement(htmlTree)) {
+		throw new Error("Expected an HTML element as output from table node transformation.");
+	}
+
+	htmlTree.properties.class = "table table-striped table-hover";
+
+	// Convert the HTML AST to a string.
+	const htmlString = HtmlRenderer.renderHtml(htmlTree, { prettyFormatting: true });
+
+	return [
+		{
+			type: "html",
+			value: htmlString,
+		},
+	];
+};