feat(docs): add anchor links on description terms (#8413)

Problem: There is no easy way to link to an element of a description list. Solution: Automatically add `<a>` links pointing to the id of the `<dt>`. Co-authored-by: Claas Augner <[email protected]>
mdn · Oct 11, 2023 · ff73a32 · ff73a32
1 parent 8bf7a7e
commit ff73a32
Show file tree

Hide file tree

Showing 4 changed files with 57 additions and 35 deletions.
diff --git a/client/src/document/index.scss b/client/src/document/index.scss
@@ -75,23 +75,6 @@
       }
     }
 
-    &[id^="attr-"] {
-      &:link,
-      &:visited {
-        color: var(--text-link);
-        text-decoration: none;
-      }
-
-      &:hover,
-      &:focus {
-        text-decoration: underline;
-      }
-
-      &:active {
-        color: #fff;
-      }
-    }
-
     &[aria-current] {
       color: var(--text-link);
       font-weight: var(--font-body-strong-weight);
@@ -161,6 +144,35 @@
     dt {
       margin-bottom: 0.5rem;
       margin-top: 2rem;
+
+      a {
+        &:link,
+        &:visited {
+          color: inherit;
+          text-decoration: none;
+        }
+
+        &:hover,
+        &:focus {
+          text-decoration: underline;
+        }
+
+        &[href^="#"] {
+          position: relative;
+
+          &:hover::before {
+            color: var(--text-inactive);
+            content: "#";
+            display: inline-flex;
+            font-size: 0.7em;
+            left: -0.75em;
+            line-height: 1;
+            position: absolute;
+            text-decoration: none;
+            top: 0.5em;
+          }
+        }
+      }
     }
 
     dd {

diff --git a/kumascript/src/api/util.ts b/kumascript/src/api/util.ts
@@ -222,6 +222,13 @@ export class HTMLTool {
       }
       knownIDs.add(id);
       $element.attr("id", id);
+
+      if (isDt) {
+        $element
+          .find("a[data-link-to-id = true]")
+          .attr("href", "#" + id)
+          .removeAttr("data-link-to-id");
+      }
     });
     return this;
   }

diff --git a/markdown/m2h/handlers/dl.ts b/markdown/m2h/handlers/dl.ts
@@ -37,19 +37,22 @@ export function asDefinitionList(h, node) {
     paragraph.children[0].value = paragraph.children[0].value.slice(
       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",
-        {},
-        all(h, {
-          ...node,
-          children:
-            terms.length == 1 && terms[0].type == "paragraph"
-              ? terms[0].children
-              : terms,
-        })
-      ),
+      h(node, "dt", {}, dtChildren),
       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
@@ -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 term</dt>
+  <dt><a data-link-to-id="true">a term</a></dt>
   <dd>
     <p>a definition</p>
   </dd>
-  <dt>another term</dt>
+  <dt><a data-link-to-id="true">another term</a></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 nested term</dt>
+      <dt><a data-link-to-id="true">a nested term</a></dt>
       <dd>
         <p>a definition</p>
       </dd>
-      <dt>another nested term</dt>
+      <dt><a data-link-to-id="true">another nested term</a></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>with terms</dt>
+    <dt><a data-link-to-id="true">with terms</a></dt>
     <dd>
       <p>that have definitions</p>
     </dd>
-    <dt>and more terms</dt>
+    <dt><a data-link-to-id="true">and more terms</a></dt>
     <dd>
       <p>and as usual, the definitions can include block elements:</p>
       <pre class="brush: css">.likeCodeBlocks {