build(docs): Update api-markdown-documenter to 0.21.0 #25072
Conversation
…n into its own type
This reverts commit 835b417.
…cs/update-api-markdown-documenter-for-mdast-changes
…sformation (#24787) Updates the library with a new transformation layer that converts the `DocumentationNode` representation to [mdast](https://github.com/syntax-tree/mdast), and replaces the library's custom Markdown rendering with [mdast-util-to-markdown](https://github.com/syntax-tree/mdast-util-to-markdown). For an example of how the website build will be updated in response to these changes, see here: #25072.
…sformation (microsoft#24787) Updates the library with a new transformation layer that converts the `DocumentationNode` representation to [mdast](https://github.com/syntax-tree/mdast), and replaces the library's custom Markdown rendering with [mdast-util-to-markdown](https://github.com/syntax-tree/mdast-util-to-markdown). For an example of how the website build will be updated in response to these changes, see here: microsoft#25072.
tools/api-markdown-documenter/src/documentation-domain/index.ts
Outdated
Show resolved
Hide resolved
https://github.com/Josmithr/FluidFramework into docs/update-api-markdown-documenter-for-mdast-changes
Josmithr
changed the title
There was a problem hiding this comment.
Pull Request Overview
This PR updates the dependency on @fluid-tools/api-markdown-documenter to version 0.21.0 and refactors the documentation build infrastructure to use the library's new API changes.
- Updates dependency from
0.20.0to0.21.0and adds required new dependencies - Replaces custom Markdown rendering with custom transformations from Documentation domain to mdast
- Migrates from deprecated renderer-based approach to new transformation-based approach
Reviewed Changes
Copilot reviewed 6 out of 7 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/package.json | Updates API markdown documenter dependency and adds new required type definitions |
| docs/infra/api-markdown-documenter/render-api-documentation.mjs | Migrates from custom renderers to custom transformations API |
| docs/infra/api-markdown-documenter/custom-transformations.mjs | New file implementing transformations for admonition and table nodes |
| docs/infra/api-markdown-documenter/custom-renderers.mjs | Removed file containing deprecated renderer implementations |
| docs/infra/api-markdown-documenter/api-documentation-layout.mjs | Updates node construction to use new API patterns |
| docs/infra/api-markdown-documenter/admonition-node.mjs | Adds new toMarkdown method and updates type system |
Files not reviewed (1)
- docs/pnpm-lock.yaml: Language not supported
| @@ -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([ | |||
There was a problem hiding this comment.
Note for reviewers: Directives in mdast require block content children. All of the spans here have been updated to be paragraphs.
| @@ -305,7 +304,7 @@ function createDeprecationNoticeSection(apiItem, config) { | |||
|
|
|||
| return new AdmonitionNode( | |||
| transformedDeprecatedBlockContents, | |||
| "Warning", | |||
| "warning", | |||
There was a problem hiding this comment.
Note for reviewers: this was technically a bug. We were implicitly working around it by converting the string to lower case in rendering.
|
🔗 No broken links found! ✅ Your attention to detail is admirable. linkcheck output |
| * @param {string | undefined} title - (Optional) Title text for the admonition. | ||
| */ | ||
| constructor(children, admonitionKind, title) { | ||
| super(children); | ||
|
|
||
| this.type = admonitionNodeType; | ||
| this.type = "admonition"; |
There was a problem hiding this comment.
Admonition -> admonition is expected? Maybe similar to the Warning -> warning in another file?
There was a problem hiding this comment.
Yeah. It's mostly an arbitrary change (the only thing that matters is that the corresponding transformation be registered with the same key), but camelCase is more in line with mdast standard practice than PascalCase.
| throw new Error("Expected an HTML element as output from table node transformation."); | ||
| } | ||
|
|
||
| htmlTree.properties.class = "table table-striped table-hover"; |
There was a problem hiding this comment.
This is existing behavior, just ported to the mdast layer instead of via custom HTML rendering. This is how we currently apply the desired styling to our generated tables. Or am I misunderstanding the question?
There was a problem hiding this comment.
Oh, I missed that they were already there in the deleted file. My bad :).
Updates the dependency on
@fluid-tools/api-markdown-documenterto0.21.0and updates the docs build infra to accommodate / leverage API changes.Most notably: custom Markdown rendering is replaced with custom transformations from the library's "Documentation domain" to
mdast(which is then rendered bymdast-util-to-markdown.