diff --git a/tools/api-markdown-documenter/CHANGELOG.md b/tools/api-markdown-documenter/CHANGELOG.md
index 47ddd447120c..c5b94e4d87e0 100644
--- a/tools/api-markdown-documenter/CHANGELOG.md
+++ b/tools/api-markdown-documenter/CHANGELOG.md
@@ -1,5 +1,17 @@
# @fluid-tools/api-markdown-documenter
+## 0.17.0
+
+### ⚠ BREAKING CHANGES
+
+- Support for embedded HTML contents in TSDoc comments has been removed.
+ The TSDoc parser has some half-baked support for preserving HTML tags in its output, despite the TSDoc spec making no claims about supporting embedded HTML.
+ But it does so in a structure that is difficult to handle correctly, assuming that the output language can support arbitrary HTML contents, and that it is safe to output the contents raw and unsanitized.
+ As a result, this library's support for such contents was similarly half-baked, and difficult to maintain.
+ VSCode Intellisense, as a comparison, chooses to completely ignore HTML tags, and simply render the inner contents ignoring any HTML decorators.
+ This library has adopted the same policy.
+ If you depended on HTML content preservation, this change will break you.
+
## 0.16.1
- Promote `toHtml` transformation functions to `@public`.
diff --git a/tools/api-markdown-documenter/README.md b/tools/api-markdown-documenter/README.md
index 4a9939939f85..f6aa1ce3c113 100644
--- a/tools/api-markdown-documenter/README.md
+++ b/tools/api-markdown-documenter/README.md
@@ -109,6 +109,16 @@ The input `ApiModel` here will generally be the output of [API-Extractor][].
See [Documentation Domain](#documentation-domain) below for more details on the output format.
+##### Limitations
+
+###### Embedded HTML
+
+Note: `TSDoc`'s parser has limited support for preserving `HTML` tags in `TSDoc` comments.
+This library does not preserve embedded `HTML` in doc comments.
+Instead, any `HTML` tags found will be discarded, and the contents within will be rendered normally.
+This matches VSCode Intellisense's behavior.
+We may reconsider this in the future.
+
#### MarkdownRenderer
The `MarkdownRenderer` namespace includes a few functions for generating Markdown contents.
diff --git a/tools/api-markdown-documenter/package.json b/tools/api-markdown-documenter/package.json
index b89c5896324d..c89f555bcce3 100644
--- a/tools/api-markdown-documenter/package.json
+++ b/tools/api-markdown-documenter/package.json
@@ -1,6 +1,6 @@
{
"name": "@fluid-tools/api-markdown-documenter",
- "version": "0.16.1",
+ "version": "0.17.0",
"description": "Processes .api.json files generated by API-Extractor and generates Markdown documentation from them.",
"homepage": "https://fluidframework.com",
"repository": {
diff --git a/tools/api-markdown-documenter/src/api-item-transforms/TsdocNodeTransforms.ts b/tools/api-markdown-documenter/src/api-item-transforms/TsdocNodeTransforms.ts
index d44b25cefd58..3539fa012e8a 100644
--- a/tools/api-markdown-documenter/src/api-item-transforms/TsdocNodeTransforms.ts
+++ b/tools/api-markdown-documenter/src/api-item-transforms/TsdocNodeTransforms.ts
@@ -9,8 +9,6 @@ import {
type DocDeclarationReference,
type DocEscapedText,
type DocFencedCode,
- type DocHtmlEndTag,
- type DocHtmlStartTag,
type DocLinkTag,
type DocNode,
DocNodeKind,
@@ -111,11 +109,13 @@ export function _transformTsdocNode(
case DocNodeKind.FencedCode: {
return transformTsdocFencedCode(node as DocFencedCode, options);
}
- case DocNodeKind.HtmlStartTag: {
- return transformTsdocHtmlTag(node as DocHtmlStartTag, options);
- }
+ case DocNodeKind.HtmlStartTag:
case DocNodeKind.HtmlEndTag: {
- return transformTsdocHtmlTag(node as DocHtmlEndTag, options);
+ // This matches intellisense's policy for HTML in TSDoc/JSDoc comments.
+ options.logger?.error(
+ `Encountered an HTML tag. This library does not support embedded HTML content. Inner contents will be mapped as normal, but the HTML tags will be ignored.`,
+ );
+ return undefined;
}
case DocNodeKind.InheritDocTag: {
options.logger?.error(
@@ -205,19 +205,6 @@ export function transformTsdocEscapedText(
return new PlainTextNode(node.encodedText, /* escaped: */ true);
}
-/**
- * Converts a {@link @microsoft/tsdoc#DocHtmlStartTag} | {@link @microsoft/tsdoc#DocHtmlEndTag} to a {@link PlainTextNode}.
- */
-export function transformTsdocHtmlTag(
- node: DocHtmlStartTag | DocHtmlEndTag,
- options: TsdocNodeTransformOptions,
-): PlainTextNode {
- // TODO: this really isn't right. Mapping this forward as plain text assumes that any output format can support embedded HTML.
- // That is valid for HTML and Markdown, but not necessarily for other formats.
- // Instead, we should map embedded HTML content forward in an encapsulated format, and let the renderer decide how to handle it.
- return new PlainTextNode(node.emitAsHtml(), /* escaped: */ true);
-}
-
/**
* Converts a {@link @microsoft/tsdoc#DocPlainText} to a {@link PlainTextNode}.
*/
diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/index.html
index 07fafdcbbc34..c9f2386e2ff2 100644
--- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/index.html
+++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/index.html
@@ -29,7 +29,7 @@
test-suite-a
- Test package
+ Test package
|
diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/test-suite-a.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/test-suite-a.html
index fb2228d2dcf0..cff6bdd28724 100644
--- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/test-suite-a.html
+++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/test-suite-a.html
@@ -15,7 +15,7 @@
- Test package
+ Test package
diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/index.html
index e045c6ec6be5..a7349c952714 100644
--- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/index.html
+++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/index.html
@@ -25,7 +25,7 @@
test-suite-a
- Test package
+ Test package
|
diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/test-suite-a.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/test-suite-a.html
index 0f053f6d7fb3..eb85534a2c0f 100644
--- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/test-suite-a.html
+++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/test-suite-a.html
@@ -11,7 +11,7 @@
- Test package
+ Test package
diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/index.html
index 0037a2e64a79..a0e9e1c9fd06 100644
--- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/index.html
+++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/index.html
@@ -29,7 +29,7 @@
test-suite-a
- Test package
+ Test package
|
diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/test-suite-a.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/test-suite-a.html
index 718be8690011..4495b6100c27 100644
--- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/test-suite-a.html
+++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/test-suite-a.html
@@ -10,7 +10,7 @@
- Test package
+ Test package
diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/index.md
index 8c37de65cfa2..2291952e5438 100644
--- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/index.md
+++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/index.md
@@ -4,5 +4,5 @@
| Package | Description |
| --- | --- |
-| [test-suite-a](./test-suite-a) | Test package |
+| [test-suite-a](./test-suite-a) | Test package |
| [test-suite-b](./test-suite-b) | |
diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/test-suite-a.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/test-suite-a.md
index 7ad602419aff..46fa71786f4e 100644
--- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/test-suite-a.md
+++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/test-suite-a.md
@@ -2,7 +2,7 @@
[Packages](./) > [test-suite-a](./test-suite-a)
-Test package
+Test package
## Remarks {#test-suite-a-remarks}
diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/index.md
index d7a292a666cc..b5d15fa03386 100644
--- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/index.md
+++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/index.md
@@ -2,5 +2,5 @@
| Package | Description |
| --- | --- |
-| [test-suite-a](docs/test-suite-a) | Test package |
+| [test-suite-a](docs/test-suite-a) | Test package |
| [test-suite-b](docs/test-suite-b) | |
diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/test-suite-a.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/test-suite-a.md
index aaf6dcf8dc62..7366c338c454 100644
--- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/test-suite-a.md
+++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/test-suite-a.md
@@ -1,6 +1,6 @@
[Packages](docs/) > [test-suite-a](docs/test-suite-a)
-Test package
+Test package
# Remarks {#test-suite-a-remarks}
diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/sparse-config/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/sparse-config/index.md
index 1774e3b0901b..519e8d9d44cc 100644
--- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/sparse-config/index.md
+++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/sparse-config/index.md
@@ -4,5 +4,5 @@
| Package | Description |
| --- | --- |
-| [test-suite-a](docs/test-suite-a) | Test package |
+| [test-suite-a](docs/test-suite-a) | Test package |
| [test-suite-b](docs/test-suite-b) | |
diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/sparse-config/test-suite-a.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/sparse-config/test-suite-a.md
index f9818fae3535..928ecaac6a6d 100644
--- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/sparse-config/test-suite-a.md
+++ b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/sparse-config/test-suite-a.md
@@ -1,6 +1,6 @@
## test-suite-a
-Test package
+Test package
### Remarks {#test-suite-a-remarks}