refactor(api-markdown-documenter): Update Documentation Domain to be more restrictive

[Josmithr]

Background

The Documentation Domain (DocumentationNode and its implementations) was created with a goal of being very flexible in the kinds of trees of content it could express. This was accomplished by, in most cases, allowing parent nodes to contain any kind of child content (with a couple of exceptions). This ultimately ended up creating problems in terms of Markdown-compatibility in particular (HTML is more expressive, so compat there was less of an issue). There are also some forms of hierarchy allowed by the system (and inadvertently used by the system) that don't make sense (e.g., parenting a SectionNode under a ParagraphNode.

As this library has evolved, I have become more and more convinced that the Documentation Domain is unnecessary and should be removed. In this world, ApiItem transformations would output mdast (Markdown Syntax Trees) directly, instead of going through an intermediary domain. mdast has a vast support ecosystem, so it seems like a much better target than some bespoke intermediary domain.

This PR

This PR is an attempt to begin aligning the Documentation Domain with Markdown syntax requirements by restricting the kinds of contents that can appear under specific kinds of nodes.

It also introduces a new pattern for domain extension, which itself aligns with how the broader unist ecosystem accomplishes extensibility. We require this extensibility internally, as our fluidframework.com website build actually does extend the Documentation Domain with a custom node type. In the future, this can be trivially mapped to a custom mdast node, but for now we need to support it.

Immediate impact

See the updated HTML test assets for the immediate impact on the output format. Note the reduction in unnecessary hierarchy.

[Copilot]

Pull Request Overview

This PR tightens up the Documentation Domain API to enforce Markdown-compatible content hierarchies, updates HTML and TSDoc transformers to use the new node properties, and introduces utilities for table-cell inlining and newline pruning.

• Restrict block vs. phrasing content via BlockContentMap/PhrasingContentMap and update constructors to use text/value properties.
• Revise default HTML transformations to consume the new single-child signatures.
• Add transformTsdocSectionForTableCell and refine newline-collapse and adjacent-newline filters for more concise tables.

Reviewed Changes

Copilot reviewed 77 out of 77 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
tools/api-markdown-documenter/src/documentation-domain/BlockContent.ts	New strict BlockContentMap/BlockContent types
tools/api-markdown-documenter/src/documentation-domain-to-html/default-transformations	Updated transforms to use node.text and node.value
tools/api-markdown-documenter/src/documentation-domain-to-html/test	Tests updated to match new single-child constructors
tools/api-markdown-documenter/src/api-item-transforms/helpers/TableHelpers.ts	Introduced transformTsdocSectionForTableCell
tools/api-markdown-documenter/src/api-item-transforms/TsdocNodeTransforms.ts	Refactored TSDoc transforms, added newline utilities
tools/api-markdown-documenter/src/api-item-transforms/helpers/Helpers.ts	Swapped to PhrasingContent/SectionContent maps
tools/api-markdown-documenter/README.md	Documented new extensibility model

Comments suppressed due to low confidence (3)

tools/api-markdown-documenter/src/api-item-transforms/helpers/TableHelpers.ts:847

• Add unit tests for transformTsdocSectionForTableCell to verify that a single-paragraph section inlines correctly and that multiple-paragraph sections are preserved.

function transformTsdocSectionForTableCell(

tools/api-markdown-documenter/src/api-item-transforms/TsdocNodeTransforms.ts:417

• Add tests for collapseAdjacentLineBreaks to ensure consecutive line breaks collapse into a single break as expected.

function collapseAdjacentLineBreaks(nodes: readonly PhrasingContent[]): PhrasingContent[] {

tools/api-markdown-documenter/src/api-item-transforms/TsdocNodeTransforms.ts:481

• Add tests for filterNewlinesAdjacentToParagraphs to cover scenarios where line breaks immediately before or after paragraph nodes should be stripped.

function filterNewlinesAdjacentToParagraphs(nodes: readonly BlockContent[]): BlockContent[] {

[github-actions]

🔗 No broken links found! ✅

Your attention to detail is admirable.

linkcheck output

> [email protected] ci:check-links /home/runner/work/FluidFramework/FluidFramework/docs
> start-server-and-test "npm run serve -- --no-open" 3000 check-links

1: starting server using command "npm run serve -- --no-open"
and when url "[ 'http://127.0.0.1:3000' ]" is responding with HTTP status code 200
running tests using command "npm run check-links"


> [email protected] serve
> docusaurus serve --no-open

[SUCCESS] Serving "build" directory at: http://localhost:3000/

> [email protected] check-links
> linkcheck http://localhost:3000 --skip-file skipped-urls.txt

Crawling...

Stats:
  222975 links
    1707 destination URLs
    1939 URLs ignored
       0 warnings
       0 errors

[tylerbutler]

I haven't had a chance to review the changes yet but I love this direction. Being able to easily tap into the unist ecosystem is powerful.

[Josmithr]

I haven't had a chance to review the changes yet but I love this direction. Being able to easily tap into the unist ecosystem is powerful.

Let me know if you want to chat at some point. Happy to bring you up to speed on the current state / planned direction. I'd also be interesting exploring the ability to take TypeDoc's representation as another supported input format.