Extract headings without Nextra

Author: hasparus

pnpm-lock.yaml

@@ -6,8 +6,8 @@ import { ServerComponentMarkdown } from "@/app/conf/_components/server-component
 import { Button } from "@/app/conf/_design-system/button"
 
 import { NavbarPlaceholder } from "../components/navbar"
-import "../resources/prose.css"
 import { Hero, HeroStripes } from "../components/hero"
+import "../resources/prose.css"
 
 import markdown from "./code-of-conduct.mdx?raw"
 
@@ -42,6 +42,29 @@ export default function ResourcesPage() {
         <div className="gql-conf-container gql-conf-section gql-prose xl:mb-16 xl:mt-8">
           <ServerComponentMarkdown
             markdown={markdown}
+            extractToc
+            Wrapper={({ children, data }) => {
+              return (
+                <div>
+                  <aside className="gql-sticky-aside row-span-8 -mt-1 w-fit sm:max-xl:grid sm:max-xl:grid-cols-2 sm:max-xl:bg-neu-100 sm:max-xl:p-4 dark:sm:max-xl:bg-neu-50/50">
+                    {data.toc.map(({ value, id, depth }) => (
+                      <a
+                        key={id}
+                        data-depth={depth}
+                        className="raw typography-menu block p-4 py-2 text-neu-800 hover:bg-neu-100 hover:text-neu-900 data-[depth=2]:font-semibold dark:hover:bg-neu-50 max-xl:-ml-4 xl:data-[depth=2]:text-lg"
+                        style={{
+                          paddingLeft: (depth - 2) * 16 + 16,
+                        }}
+                        href={`#${id}`}
+                      >
+                        {value}
+                      </a>
+                    ))}
+                  </aside>
+                  {children}
+                </div>
+              )
+            }}
             components={{
               a: (props: React.AnchorHTMLAttributes<HTMLAnchorElement>) => {
                 return (

src/app/conf/2025/code-of-conduct/page.tsx

@@ -1,8 +1,13 @@
 import "server-only"
 
 // @ts-expect-error - we already have it in transitive deps and I want to avoid having a duplicate
-import { evaluate } from "@mdx-js/mdx"
+import { compile, run } from "@mdx-js/mdx"
 import * as runtime from "react/jsx-runtime"
+import { Root, Element } from "hast"
+import { visit } from "unist-util-visit"
+import { toString } from "hast-util-to-string"
+// @ts-expect-error
+import Slugger from "github-slugger"
 
 /**
  * Nextra's builtin MDX support requires jumping out to a Client component
@@ -14,25 +19,68 @@ import * as runtime from "react/jsx-runtime"
 export async function ServerComponentMarkdown({
   markdown,
   components = {},
+  extractToc = false,
+  Wrapper = ({ children }) => children,
 }: {
   markdown: string
   components?: Record<string, React.ComponentType>
+  extractToc?: boolean
+  Wrapper?: React.ComponentType<{
+    children: React.ReactNode
+    data: { toc: TableOfContents }
+  }>
 }) {
   try {
-    const { default: Mdx } = await evaluate(markdown, {
+    const rehypePlugins = extractToc ? [rehypeExtractTableOfContents] : []
+
+    const vfile = await compile(markdown, {
+      outputFormat: "function-body",
+      remarkPlugins: [],
+      rehypePlugins,
+      recmaPlugins: [],
+    })
+
+    const { default: Mdx } = await run(String(vfile), {
       ...runtime,
-      useMDXComponents: (arg: typeof components) => {
-        return {
-          ...components,
-          ...arg,
-        }
-      },
+      baseUrl: import.meta.url,
     })
-    return Mdx()
+
+    return <Wrapper data={vfile.data}>{Mdx({ components })}</Wrapper>
   } catch (error) {
     console.error(error)
     return (
       <div>{error instanceof Error ? error.message : "Error loading MDX"}</div>
     )
   }
 }
+
+type TableOfContents = Array<{ value: string; id: string; depth: number }>
+
+/**
+ * Nextra has a built-in plugin like this, but it also steals the heading contents
+ * as is tightly coupled with other Nextra features.
+ */
+function rehypeExtractTableOfContents() {
+  const slugger = new Slugger()
+
+  return function (tree: Root, file: any) {
+    const toc: TableOfContents = []
+
+    visit(tree, "element", (node: Element) => {
+      if (node.tagName && /^h[1-6]$/.test(node.tagName)) {
+        const depth = parseInt(node.tagName.charAt(1), 10)
+        const value = toString(node)
+        const slug = slugger.slug(value)
+
+        node.properties ||= node.properties || {}
+        // add id to the heading element if it's not already set
+        node.properties.id ||= slug
+
+        toc.push({ value, id: slug, depth })
+      }
+    })
+
+    file.data = file.data || {}
+    file.data.toc = toc
+  }
+}