Generate markdown TOC (#296)

* derive table of contents from markdown, making use of unified.js
* embellish the generated html for markdown to include header id's
* remove next-mdx-remote and mdxjs, now that remark and rehype are being used directly

Author: kanishka-work

bindings/Unified.res

@@ -0,0 +1,48 @@
+module MarkdownTableOfContents = {
+  type rec toc = {
+    label: string,
+    id: string,
+    children: list<toc>,
+  }
+
+  type t = list<toc>
+}
+
+type processor
+
+@module("unified") external unified: unit => processor = "default"
+
+type node = {\"type": string, depth: option<int>}
+
+type data = {id: string}
+
+type headingnode = {
+  depth: int,
+  data: data,
+}
+
+external asHeadingNode: node => headingnode = "%identity"
+
+type rootnode = {children: array<node>}
+
+type vfile = {mutable toc: MarkdownTableOfContents.t, contents: string}
+
+type transformer = (rootnode, vfile) => unit
+
+type attacher = unit => transformer
+
+@send external use: (processor, attacher) => processor = "use"
+
+@send external process: (processor, string) => Js.Promise.t<vfile> = "process"
+
+@module("remark-slug") external remarkSlug: attacher = "default"
+
+@module("remark-parse") external remarkParse: attacher = "default"
+
+@module("remark-rehype") external remark2rehype: attacher = "default"
+
+@module("rehype-stringify") external rehypeStringify: attacher = "default"
+
+module MdastUtilToString = {
+  @module("mdast-util-to-string") external toString: headingnode => string = "default"
+}

bindings/Unified.resi

@@ -0,0 +1,48 @@
+module MarkdownTableOfContents: {
+  type rec toc = {
+    label: string,
+    id: string,
+    children: list<toc>,
+  }
+
+  type t = list<toc>
+}
+
+type processor
+
+let unified: unit => processor
+
+type node = {\"type": string, depth: option<int>}
+
+type data = {id: string}
+
+type headingnode = {
+  depth: int,
+  data: data,
+}
+
+let asHeadingNode: node => headingnode
+
+type rootnode = {children: array<node>}
+
+type vfile = {mutable toc: MarkdownTableOfContents.t, contents: string}
+
+type transformer = (rootnode, vfile) => unit
+
+type attacher = unit => transformer
+
+let use: (processor, attacher) => processor
+
+let process: (processor, string) => Js.Promise.t<vfile>
+
+let remarkSlug: attacher
+
+let remarkParse: attacher
+
+let remark2rehype: attacher
+
+let rehypeStringify: attacher
+
+module MdastUtilToString: {
+  let toString: headingnode => string
+}

common/MdastToc.res

@@ -0,0 +1,62 @@
+// TODO: define scanleft (https://github.com/reazen/relude/blob/e733128d0df8022448398a44c80cba6f28443b94/src/list/Relude_List_Base.re#L487)
+// and use it below
+
+// TODO: factor out the core algorithm from other concerns, and
+//  write unit tests for the core algorithm.
+
+let transformer = (rootnode: Unified.rootnode, file: Unified.vfile) => {
+  let rec collect = (nodes, inProgress) => {
+    switch nodes {
+    | list{} =>
+      switch inProgress {
+      | None => list{}
+      | Some(_, entry) => list{entry}
+      }
+    | list{h: Unified.headingnode, ...tail} =>
+      let d = h.depth
+      if d >= 2 || d <= 3 {
+        let entry = {
+          Unified.MarkdownTableOfContents.label: Unified.MdastUtilToString.toString(h),
+          id: h.data.id,
+          children: list{},
+        }
+        switch inProgress {
+        | None => collect(tail, Some(d, entry))
+        | Some(lastRootDepth, inProgress) if d <= lastRootDepth => list{
+            inProgress,
+            ...collect(tail, Some(d, entry)),
+          }
+        | Some(lastRootDepth, inProgress) =>
+          let inProgress = {
+            ...inProgress,
+            children: Belt.List.concat(inProgress.children, list{entry}),
+          }
+          collect(tail, Some(lastRootDepth, inProgress))
+        }
+      } else {
+        // TODO: Should we guard against unusual jumps in depth here?
+        //  No, instead validate the list of headings
+        //  in an earlier pass and produce new type with
+        //  stronger guarantees about heading sequences.
+        collect(tail, inProgress)
+      }
+    }
+  }
+  let headings = collect(
+    Array.to_list(
+      Belt.Array.keepMap(rootnode.children, ch =>
+        switch ch {
+        | {\"type": "heading", depth: Some(_)} => Some(Unified.asHeadingNode(ch))
+        | _ => None
+        }
+      ),
+    ),
+    None,
+  )
+
+  file.toc = headings
+}
+
+let plugin = () => {
+  transformer
+}

common/MdastToc.resi

@@ -0,0 +1 @@
+let plugin: Unified.attacher

common/Mdx.res

@@ -2,28 +2,17 @@ let s = React.string
 
 module MarkdownPageBody = {
   @react.component
-  let make = (~margins, ~children) =>
-    <div className={margins ++ ` prose prose-yellow prose-lg text-gray-500 mx-auto`}>
-      children
-    </div>
+  let make = (~margins, ~renderedMarkdown) =>
+    <div
+      className={margins ++ ` prose prose-yellow prose-lg text-gray-500 mx-auto`}
+      dangerouslySetInnerHTML={{"__html": renderedMarkdown}}
+    />
 }
 
 module TableOfContents = {
-  // TODO: define general heading tree type and recursively traverse when rendering
-  type subHeading = {
-    subName: string,
-    subHeadingId: string,
-  }
-
-  type heading = {
-    name: string,
-    headingId: string,
-    subHeadings: array<subHeading>,
-  }
-
   type t = {
     contents: string,
-    headings: array<heading>,
+    toc: Unified.MarkdownTableOfContents.t,
   }
 
   @react.component
@@ -32,29 +21,30 @@ module TableOfContents = {
       className="hidden lg:sticky lg:self-start lg:top-2 lg:flex lg:flex-col lg:col-span-2 border-r border-gray-200 pt-5 pb-4 overflow-y-auto">
       <div className="px-4"> <span className="text-lg"> {s(content.contents)} </span> </div>
       <div className="mt-5 ">
+        // TODO: implement a completely general recursive traversal a toc forest
         <nav className="px-2 space-y-1" ariaLabel="Sidebar">
-          {content.headings
-          |> Js.Array.mapi((hdg, idx) =>
+          {content.toc
+          ->Belt.List.mapWithIndex((idx, hdg) =>
             <div key={Js.Int.toString(idx)} className="space-y-1">
               // Expanded: "text-gray-400 rotate-90", Collapsed: "text-gray-300"
               <a
-                href={"#" ++ hdg.headingId}
+                href={"#" ++ hdg.id}
                 className="block text-gray-600 hover:text-gray-900 pr-2 py-2 text-sm font-medium">
-                {s(hdg.name)}
+                {s(hdg.label)}
               </a>
-              {hdg.subHeadings
-              |> Js.Array.mapi((sub, idx) =>
+              {hdg.children
+              ->Belt.List.mapWithIndex((idx, sub) =>
                 <a
-                  href={"#" ++ sub.subHeadingId}
+                  href={"#" ++ sub.id}
                   className="block pl-6 pr-2 py-2 text-sm font-medium text-gray-600 hover:text-gray-900"
                   key={Js.Int.toString(idx)}>
-                  {s(sub.subName)}
+                  {s(sub.label)}
                 </a>
               )
-              |> React.array}
+              ->Belt.List.toArray |> React.array}
             </div>
           )
-          |> React.array}
+          ->Belt.List.toArray |> React.array}
         </nav>
       </div>
     </div>