From 0d97fc44d5dd6c70c330455465edbf0b3e6f4988 Mon Sep 17 00:00:00 2001
From: Max Schmitt <max@schmitt.mx>
Date: Wed, 11 Sep 2024 14:17:35 +0200
Subject: [PATCH] docs(markdown): parse :::note's text as MD elements

---
 utils/doclint/documentation.js | 6 +++---
 utils/markdown.js              | 7 ++++---
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/utils/doclint/documentation.js b/utils/doclint/documentation.js
index 77b20ca7694ce..e4d9a16b09aec 100644
--- a/utils/doclint/documentation.js
+++ b/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'
+      node.text = `**NOTE** ` + (node.children || []).map(child => md.render([child], { flattenText: false, omitLastCR: true })).join('↵')
     }
   });
   // 5 is a typical member doc offset.
-  return md.render(comments, { maxColumns: 120 - 5, omitLastCR: true, flattenText: true });
+  return md.render(comments,  { maxColumns: 120 - 5, omitLastCR: true, flattenText: true });
 }
 
 /**
diff --git a/utils/markdown.js b/utils/markdown.js
index a8ae8d4360286..928b918e358f2 100644
--- a/utils/markdown.js
+++ b/utils/markdown.js
@@ -50,7 +50,6 @@
 
 /** @typedef {MarkdownBaseNode & {
  *    type: 'note',
- *    text: string,
  *    noteType: string,
  *  }} MarkdownNoteNode */
 
@@ -208,7 +207,7 @@ function buildTree(lines) {
         tokens.push(line.substring(indent.length));
         line = lines[++i];
       }
-      node.text = tokens.join('↵');
+      node.children = buildTree(tokens);
       appendNode(indent, node);
       continue;
     }
@@ -341,7 +340,9 @@ function innerRenderMdNode(indent, node, lastNode, result, options) {
   if (node.type === 'note') {
     newLine();
     result.push(`${indent}:::${node.noteType}`);
-    result.push(wrapText(node.text, options, indent));
+    const children = node.children || [];
+    for (const child of children)
+      innerRenderMdNode(indent, child, children[children.length - 1], result, options);
     result.push(`${indent}:::`);
     newLine();
     return;