fix(docs): link first child of every description term in post-process…

…ing (#9862)

- Adds links only in post-processing (not in m2h).
- Wraps every first content element (not only `<code>`), unless it is/contains a link.

Co-authored-by: Claas Augner <caugner@mozilla.com>

kumascript/src/api/util.ts

@@ -224,15 +224,11 @@ export class HTMLTool {
       $element.attr("id", id);
 
       if (isDt) {
-        // Remove empty anchor links.
-        // This happens if the term already links to a page.
-        $element.find("a[data-link-to-id = true]:empty").remove();
-
-        // Link remaining anchor links to the term's ID.
-        $element
-          .find("a[data-link-to-id = true]")
-          .attr("href", "#" + id)
-          .removeAttr("data-link-to-id");
+        // Link the first element child to the ID.
+        const firstContent = $element.contents().first();
+        if (!firstContent.is("a") && firstContent.find("a").length === 0) {
+          $(firstContent).wrap(`<a href="#${encodeURIComponent(id)}"></a>`);
+        }
       }
     });
     return this;

markdown/m2h/handlers/dl.ts

@@ -38,21 +38,19 @@ export function asDefinitionList(h, node) {
       DEFINITION_PREFIX.length
     );
 
-    const [firstDtChild, ...dtChildren] = all(h, {
-      ...node,
-      children:
-        terms.length == 1 && terms[0].type == "paragraph"
-          ? terms[0].children
-          : terms,
-    });
-    if (firstDtChild) {
-      dtChildren.unshift(
-        h(node, "a", { "data-link-to-id": "true" }, [firstDtChild])
-      );
-    }
-
     return [
-      h(node, "dt", {}, dtChildren),
+      h(
+        node,
+        "dt",
+        {},
+        all(h, {
+          ...node,
+          children:
+            terms.length == 1 && terms[0].type == "paragraph"
+              ? terms[0].children
+              : terms,
+        })
+      ),
       h(
         node,
         "dd",

testing/content/files/en-us/markdown/tool/m2h/expected.html

@@ -11,23 +11,23 @@ <h2>Hello</h2>
 <h2>Definition lists</h2>
 <p>We have our own syntax for <code>&#x3C;dl></code>.</p>
 <dl>
-  <dt><a data-link-to-id="true">a term</a></dt>
+  <dt>a term</dt>
   <dd>
     <p>a definition</p>
   </dd>
-  <dt><a data-link-to-id="true">another term</a></dt>
+  <dt>another term</dt>
   <dd>
     <p>another definition</p>
     <p>Definitions can include block elements:</p>
     <pre class="brush: js">const suchAsCodeBlocks = true;
 </pre>
     <p>And of course <code>&#x3C;dl></code> elements can be nested inside <code>&#x3C;dd></code>:</p>
     <dl>
-      <dt><a data-link-to-id="true">a nested term</a></dt>
+      <dt>a nested term</dt>
       <dd>
         <p>a definition</p>
       </dd>
-      <dt><a data-link-to-id="true">another nested term</a></dt>
+      <dt>another nested term</dt>
       <dd>
         <p>another nested definition</p>
       </dd>
@@ -62,11 +62,11 @@ <h2>Callouts, notes, and warnings</h2>
   </ul>
   <p>...and even definition lists:</p>
   <dl>
-    <dt><a data-link-to-id="true">with terms</a></dt>
+    <dt>with terms</dt>
     <dd>
       <p>that have definitions</p>
     </dd>
-    <dt><a data-link-to-id="true">and more terms</a></dt>
+    <dt>and more terms</dt>
     <dd>
       <p>and as usual, the definitions can include block elements:</p>
       <pre class="brush: css">.likeCodeBlocks {

testing/tests/index.test.ts

@@ -1559,7 +1559,7 @@ test("basic markdown rendering", () => {
   expect($("article em")).toHaveLength(1);
   expect($("article ul li")).toHaveLength(6);
   expect($('article a[href^="/"]')).toHaveLength(2);
-  expect($('article a[href^="#"]')).toHaveLength(5);
+  expect($('article a[href^="#"]')).toHaveLength(6);
   expect($("article pre")).toHaveLength(4);
   expect($("article pre.notranslate")).toHaveLength(4);
   expect($("article pre.css").hasClass("brush:")).toBe(true);