From 029581391fa2a57f843d55f47390ec8c0c4b6732 Mon Sep 17 00:00:00 2001
From: Kartik Soneji <kartiksoneji@rocketmail.com>
Date: Mon, 30 Oct 2023 22:52:43 +0530
Subject: [PATCH] fix(docs): link first child of every description term in
 post-processing (#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                    | 14 ++++------
 markdown/m2h/handlers/dl.ts                   | 26 +++++++++----------
 .../en-us/markdown/tool/m2h/expected.html     | 12 ++++-----
 testing/tests/index.test.ts                   |  2 +-
 4 files changed, 24 insertions(+), 30 deletions(-)

diff --git a/kumascript/src/api/util.ts b/kumascript/src/api/util.ts
index 0e7f0c2e9cb3..3a5655b4fcb4 100644
--- a/kumascript/src/api/util.ts
+++ b/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;
diff --git a/markdown/m2h/handlers/dl.ts b/markdown/m2h/handlers/dl.ts
index 6aca68c03438..252356a1d6b2 100644
--- a/markdown/m2h/handlers/dl.ts
+++ b/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",
diff --git a/testing/content/files/en-us/markdown/tool/m2h/expected.html b/testing/content/files/en-us/markdown/tool/m2h/expected.html
index ede7e703085a..ce9a753976d4 100644
--- a/testing/content/files/en-us/markdown/tool/m2h/expected.html
+++ b/testing/content/files/en-us/markdown/tool/m2h/expected.html
@@ -11,11 +11,11 @@ <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>
@@ -23,11 +23,11 @@ <h2>Definition lists</h2>
 </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 {
diff --git a/testing/tests/index.test.ts b/testing/tests/index.test.ts
index 25c20f221c5d..ac0708f8e318 100644
--- a/testing/tests/index.test.ts
+++ b/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);