docs(markdown): parse :::note's text as MD elements #32510

mxschmitt · 2024-09-09T06:48:46Z

Two ways of fixing it, either:

a) Pass flattenText: falase to wrapText's options, but it seems to come from high up and overriding it only for :::note seems not great.
b) Parse the :::note's children as real MarkdownNotes and render them as real notes

I did b) in this case, which seems more reasonable.

Fixes #32505
Preview of the rolled docs: microsoft/playwright.dev#1503

utils/markdown.js

dgozman · 2024-09-11T12:25:48Z

utils/doclint/documentation.js

@@ -802,12 +802,12 @@ function generateSourceCodeComment(spec) {
 node.codeLang = parseCodeLang(node.codeLang).highlighter;
 if (node.type === 'note') {
 // @ts-ignore
- node.type = 'text';
- node.text = '**NOTE** ' + node.text;
+ node.type = 'text'


Why no semicolons?

its JS, we don't lint JS.

utils/doclint/documentation.js

dgozman · 2024-09-23T15:26:47Z

utils/markdown.js

+ }
+ innerRenderMdNode(indent, textNode, lastNode, result, options);
+ } else {
+ result.push(`${indent}:::${node.noteType}`);


Suggested change

result.push(`${indent}:::${node.noteType}`);

result.push(options.notePrefix || `${indent}:::${node.noteType}`);

dgozman · 2024-09-23T15:27:09Z

utils/markdown.js

+ const children = node.children ?? [];
+ for (let i = 0; i < children.length; i++)
+ innerRenderMdNode(indent, children[i], lastNode, result, options);
+ result.push(`${indent}:::`);


Suggested change

result.push(`${indent}:::`);

result.push(options.noteSuffix || `${indent}:::`);

dgozman · 2024-09-23T15:27:28Z

utils/markdown.js

- * renderCodeBlockTitlesInHeader?: boolean
+ * flattenText?: boolean,
+ * renderCodeBlockTitlesInHeader?: boolean,
+ * renderNoteAsText?: boolean,


I'd recommend notePrefix?: string, noteSuffix?: string. This way, you can render code blocks or lists inside notes, even for typescript comments.

dgozman · 2024-09-23T15:28:58Z

utils/markdown.js

+ for (let i = 0; i < children.length; i++)
+ innerRenderMdNode(indent, children[i], lastNode, result, options);


Suggested change

for (let i = 0; i < children.length; i++)

innerRenderMdNode(indent, children[i], lastNode, result, options);

for (const child of children) {

innerRenderMdNode(indent, child, lastNode, result, options);

lastNode = child;

}

github-actions · 2024-09-23T16:07:40Z

Test results for "tests 1"

1 failed
❌ [webkit-codegen-mode-trace] › library/inspector/cli-codegen-2.spec.ts:408:7 › cli codegen › click should emit events in order

1 flaky

⚠️ [chromium-library] › library/capabilities.spec.ts:141:3 › should not crash on showDirectoryPicker

36325 passed, 743 skipped
✔️✔️✔️

Merge workflow run.

mxschmitt mentioned this pull request Sep 9, 2024

chore: roll to using real children for :::note type microsoft/playwright.dev#1503

Draft

mxschmitt marked this pull request as ready for review September 9, 2024 06:49