Customize MDX links and headings

Author: hasparus

src/_design-system/mdx-components/get-mdx-headings.tsx

@@ -0,0 +1,99 @@
+/**
+ * @file MDX Heading components.
+ * Copied from `nextra-theme-docs` and restyled.
+ */
+
+import { clsx } from "clsx"
+import {
+  useSetActiveAnchor,
+  useIntersectionObserver,
+  useSlugs,
+} from "nextra-theme-docs"
+
+import { useEffect, useRef } from "react"
+
+const headingClasses = {
+  h1: "typography-h2 mt-2",
+  h2: "typography-h3 mt-10",
+  h3: "typography-body-lg mt-8",
+  h4: "typography-body-md font-semibold mt-8",
+  h5: "typography-label",
+  h6: "typography-label",
+}
+
+const createHeading = (
+  Tag: `h${2 | 3 | 4 | 5 | 6}`,
+  context: { index: number },
+) =>
+  function Heading({
+    children,
+    id,
+    className,
+    ...props
+  }: React.ComponentPropsWithoutRef<"h2">): React.ReactElement {
+    // Nextra tracks anchors in context
+    const setActiveAnchor = useSetActiveAnchor()
+    const slugs = useSlugs()
+    const observer = useIntersectionObserver()
+    const obRef = useRef<HTMLAnchorElement>(null)
+
+    useEffect(() => {
+      const heading = obRef.current
+      if (!id || !observer || !heading) return
+      observer.observe(heading)
+      slugs.set(heading, [id, (context.index += 1)])
+
+      return () => {
+        observer.disconnect()
+        slugs.delete(heading)
+        setActiveAnchor(f => {
+          const ret = { ...f }
+          delete ret[id]
+          return ret
+        })
+      }
+    }, [id, slugs, observer, setActiveAnchor])
+
+    return (
+      <Tag
+        id={id}
+        className={
+          className === "sr-only"
+            ? // can be added by footnotes
+              "sr-only"
+            : clsx(headingClasses[Tag], "text-neu-900", className)
+        }
+        {...props}
+      >
+        {children}
+        {id && (
+          <a
+            href={`#${id}`}
+            className="nextra-focus subheading-anchor"
+            aria-label="Permalink for this section"
+            ref={obRef}
+          />
+        )}
+      </Tag>
+    )
+  }
+
+export function getMdxHeadings() {
+  const counter = ((globalThis as Record<string, any>).__headingsCounter ||= {
+    index: 0,
+  })
+
+  return {
+    h1: (props: React.ComponentPropsWithoutRef<"h1">) => (
+      <h1
+        {...props}
+        className={clsx(headingClasses.h1, "text-neu-900", props.className)}
+      />
+    ),
+    h2: createHeading("h2", counter),
+    h3: createHeading("h3", counter),
+    h4: createHeading("h4", counter),
+    h5: createHeading("h5", counter),
+    h6: createHeading("h6", counter),
+  }
+}

src/_design-system/mdx-components/index.tsx

@@ -0,0 +1,7 @@
+import { getMdxHeadings } from "./get-mdx-headings"
+import { MdxLink } from "./mdx-link"
+
+export const mdxComponents = {
+  a: MdxLink,
+  ...getMdxHeadings(),
+}

src/_design-system/mdx-components/mdx-link.tsx

@@ -0,0 +1,25 @@
+import { forwardRef } from "react"
+import { clsx } from "clsx"
+
+import { Anchor } from "@/app/conf/_design-system/anchor"
+
+export const MdxLink = forwardRef<
+  HTMLAnchorElement,
+  React.ComponentPropsWithoutRef<"a">
+>(function MdxLink(props, ref) {
+  return (
+    <Anchor
+      {...props}
+      ref={ref}
+      // we remove `text-underline-position` from default Nextra link styles, because Neue Montreal font
+      // has a different underline position than system fonts, and it looks bad in Safari.
+      className={clsx(
+        "typography-link text-neu-900 decoration-from-font underline-offset-2",
+        props.className,
+      )}
+      href={props.href || ""}
+    >
+      {props.children}
+    </Anchor>
+  )
+})

theme.config.tsx

@@ -5,14 +5,16 @@ import { useRouter } from "next/router"
 
 import { GraphQLWordmarkLogo } from "./src/icons"
 import { Footer } from "@/components/footer"
+import { mdxComponents } from "@/_design-system/mdx-components"
 
 const graphQLLogo = (
   <GraphQLWordmarkLogo className="nextra-logo h-6" title="GraphQL" />
 )
 
 export default {
   backgroundColor: {
-    dark: "27,27,27",
+    light: "251,251,249",
+    dark: "13.7,14.7,10.8",
   },
   head: function useHead() {
     const { frontMatter, title: pageTitle } = useConfig()
@@ -90,10 +92,5 @@ export default {
   search: {
     placeholder: "Search…",
   },
-  // TODO: @dimaMachina try to remove pnpm patch for `nextra` package later
-  // components: {
-  //   // Override `next/image` imports from `nextra-theme-docs`
-  //   img: (props: any) =>
-  //     createElement(typeof props.src === "object" ? NextImage : "img", props),
-  // },
+  components: mdxComponents,
 } satisfies DocsThemeConfig