fix anchor links

Author: jderochervlk

package-lock.json

@@ -43,6 +43,7 @@
     "isbot": "^5",
     "lz-string": "^1.5.0",
     "mdast-util-from-markdown": "^2.0.2",
+    "mdast-util-to-string": "^4.0.0",
     "mdast-util-toc": "^7.1.0",
     "patch-package": "^8.0.1",
     "react": "^19.1.0",

package.json

@@ -70,6 +70,9 @@ external gfm: remarkPlugin = "default"
 @module("remark-validate-links")
 external validateLinks: remarkPlugin = "default"
 
+@module("mdast-util-to-string")
+external childrenToString: {..} => string = "toString"
+
 // The loadAllMdx function logs out all of the file contents as it reads them, which is noisy and not useful.
 // We can suppress that logging with this helper function.
 let allMdx = async (~filterByPaths: option<array<string>>=?) =>
@@ -199,4 +202,23 @@ let remarkReScriptPreludePlugin = makePlugin(_options =>
 
 let remarkLinkPlugin = makePlugin(_options => (tree, vfile) => remarkLinkPlugin(tree, vfile))
 
-let plugins = [remarkLinkPlugin, gfm, remarkReScriptPreludePlugin]
+// converts the inner text of headings to kebab-case IDs
+let anchorLinkPlugin = (tree, _vfile) => {
+  visit(tree, "heading", node => {
+    let planText = childrenToString(node)
+    let nodeData = switch node["data"] {
+    | Some(data) => data
+    | None => {
+        "hProperties": {
+          "id": planText->Url.normalizeAnchor,
+          "title": planText,
+        },
+      }
+    }
+    node["data"] = nodeData
+  })
+}
+
+let anchorLinkPlugin = makePlugin(_options => (tree, vfile) => anchorLinkPlugin(tree, vfile))
+
+let plugins = [remarkLinkPlugin, gfm, remarkReScriptPreludePlugin, anchorLinkPlugin]

src/Mdx.res

@@ -7,6 +7,12 @@ module String = {
      return str.replace(/-([a-z])/g, function (g) { return g[1].toUpperCase(); });
     }")
 
+  let kebabCase = string =>
+    string
+    ->String.replaceAllRegExp(/([a-z])([A-Z])/g, "$1-$2")
+    ->String.toLowerCase
+    ->String.replaceAll(" ", "-")
+
   let capitalize: string => string = %raw("str => {
       return str && str.charAt(0).toUpperCase() + str.substring(1);
     }")

src/common/Util.res

@@ -10,6 +10,7 @@ module Unsafe: {
 
 module String: {
   let camelCase: string => string
+  let kebabCase: string => string
   let capitalize: string => string
   let capitalizeSentence: string => string
   let leadingSlash: string => string

src/common/Util.resi

@@ -10,13 +10,13 @@ module H2 = {
   // We will currently hide the headline, to keep the structure,
   // but having an Elm like documentation
   @react.component
-  let make = (~id, ~children) => <>
+  let make = (~id, ~children, ~title) => <>
     <div className="mb-10 mt-20" />
-    <Markdown.H2 id> children </Markdown.H2>
+    <Markdown.H2 id title> children </Markdown.H2>
   </>
 }
 
-type aliasH2 = Markdown.H2.props<string, React.element> => React.element
+type aliasH2 = Markdown.H2.props<string, React.element, string> => React.element
 external asMarkdownH2: 'a => aliasH2 = "%identity"
 
 let default = {

src/components/ApiMarkdown.res

@@ -1,6 +1,5 @@
 // This file was automatically converted to ReScript from 'Markdown.re'
 // Check the output and make sure to delete the original file
-external childrenToString: React.element => string = "%identity"
 
 module P = {
   @react.component
@@ -110,15 +109,11 @@ module UrlBox = {
 
 // Used for creating invisible, hoverable <a> anchors for url linking
 module Anchor = {
-  // Todo: Headers with nested components don't pass a string, we need to flatten
-  // everything to a single string first before we are able to use this id transformation
-  // function
-
   @react.component
-  let make = (~id: string, ~title: string) => {
-    <span className="inline group relative" title>
+  let make = (~id: string, ~title: option<string>=?) => {
+    <span className="inline group relative" title=?title>
       <a
-        title
+        title=?title
         className="scroll-mt-30 invisible text-gray-60 opacity-50 hover:opacity-100 hover:text-gray-60 hover:cursor-pointer group-hover:visible"
         href={"#" ++ id}
         id={id}
@@ -137,20 +132,14 @@ module H1 = {
 
 module H2 = {
   @react.component
-  let make = (~id, ~children) => {
+  let make = (~id, ~children, ~title=?) => {
     // Children may not be a string
-    let title = {
-      try {
-        childrenToString(children)->Url.normalizeAnchor
-      } catch {
-      | _ => ""
-      }
-    }
+
     <>
       <h2 id className="group mt-16 mb-3 hl-3 scroll-mt-32">
         children
         <span className="ml-2">
-          <Anchor title={title} id={title} />
+          <Anchor ?title id />
         </span>
       </h2>
     </>
@@ -159,59 +148,38 @@ module H2 = {
 
 module H3 = {
   @react.component
-  let make = (~id, ~children) => {
-    let title = {
-      try {
-        childrenToString(children)->Url.normalizeAnchor
-      } catch {
-      | _ => ""
-      }
-    }
+  let make = (~id, ~children, ~title=?) => {
     <h3 id className="group mt-8 mb-4 hl-4 scroll-mt-32">
       children
       <span className="ml-2">
-        <Anchor title={title} id={title->encodeURIComponent} />
+        <Anchor ?title id={id} />
       </span>
     </h3>
   }
 }
 
 module H4 = {
   @react.component
-  let make = (~id, ~children) => {
-    let title = {
-      try {
-        childrenToString(children)->Url.normalizeAnchor
-      } catch {
-      | _ => ""
-      }
-    }
+  let make = (~id, ~children, ~title=?) => {
     <h4 id className="group mt-8 hl-5 scroll-mt-32">
       children
       <span className="ml-2">
-        <Anchor title={title} id={title->encodeURIComponent} />
+        <Anchor ?title id />
       </span>
     </h4>
   }
 }
 
 module H5 = {
   @react.component
-  let make = (~id, ~children) => {
-    let title = {
-      try {
-        childrenToString(children)->Url.normalizeAnchor
-      } catch {
-      | _ => ""
-      }
-    }
+  let make = (~id, ~children, ~title=?) => {
     <h5
       id
       className="group mt-12 mb-3 text-12 leading-2 font-sans font-semibold uppercase tracking-wide text-gray-80"
     >
       children
       <span className="ml-2">
-        <Anchor title={title} id={title->encodeURIComponent} />
+        <Anchor ?title id />
       </span>
     </h5>
   }

src/components/Markdown.res

@@ -35,7 +35,7 @@ module Anchor: {
   /* let idFormat = (id: string): string => id */
 
   @react.component
-  let make: (~id: string, ~title: string) => React.element
+  let make: (~id: string, ~title: string=?) => React.element
 }
 
 module H1: {
@@ -45,22 +45,22 @@ module H1: {
 
 module H2: {
   @react.component
-  let make: (~id: string, ~children: React.element) => React.element
+  let make: (~id: string, ~children: React.element, ~title: string=?) => React.element
 }
 
 module H3: {
   @react.component
-  let make: (~id: string, ~children: React.element) => React.element
+  let make: (~id: string, ~children: React.element, ~title: string=?) => React.element
 }
 
 module H4: {
   @react.component
-  let make: (~id: string, ~children: React.element) => React.element
+  let make: (~id: string, ~children: React.element, ~title: string=?) => React.element
 }
 
 module H5: {
   @react.component
-  let make: (~id: string, ~children: React.element) => React.element
+  let make: (~id: string, ~children: React.element, ~title: string=?) => React.element
 }
 
 module Pre: {

src/components/Markdown.resi

@@ -28,10 +28,10 @@ type t = {
   p?: P.props<React.element> => React.element,
   li?: Li.props<React.element> => React.element,
   h1?: H1.props<React.element> => React.element,
-  h2?: H2.props<string, React.element> => React.element,
-  h3?: H3.props<string, React.element> => React.element,
-  h4?: H4.props<string, React.element> => React.element,
-  h5?: H5.props<string, React.element> => React.element,
+  h2?: H2.props<string, React.element, string> => React.element,
+  h3?: H3.props<string, React.element, string> => React.element,
+  h4?: H4.props<string, React.element, string> => React.element,
+  h5?: H5.props<string, React.element, string> => React.element,
   ul?: Ul.props<React.element> => React.element,
   ol?: Ol.props<React.element> => React.element,
   table?: Table.props<React.element> => React.element,