Sharing MDX Heading Link for Enhanced Navigation

[tomfanhm]

Hello,

I wanted to share a piece of code that I've been working on. It's an MDX heading link, designed to improve the navigation experience within MDX files. This could be particularly useful for those who are creating documentation or content-rich applications using Next.js 14.0 and MDX. I'm look forward to your feedback and suggestions.

Resource: https://nextjs.org/docs/pages/building-your-application/configuring/mdx

mdx-components.tsx

import type { MDXComponents } from "mdx/types";
import Link from "next/link";
import React, { ReactElement, ReactNode } from "react";

const flatten = (text: string, child: ReactNode): string => {
  // Check if child is null or undefined
  if (child === null || child === undefined) {
    return text;
  }
  // Check if child is a string
  if (typeof child === "string") {
    return text + child;
  }
  // Check if child is a ReactElement
  if (React.isValidElement(child)) {
    return React.Children.toArray(child.props.children).reduce(flatten, text);
  }
  // If child is of other types (number, boolean, etc.), convert it to string
  return text + String(child);
};

// Adding type annotations for the props of 'HeadingRenderer'
interface HeadingProps {
  children: ReactNode;
  level: number;
}

// Converting 'HeadingRenderer' into a TypeScript component
const HeadingRenderer: React.FC<HeadingProps> = (
  props: HeadingProps
): ReactElement => {
  const children = React.Children.toArray(props.children);
  const text = children.reduce(flatten, "");
  const slug = text.toLowerCase().replace(/\W/g, "-");

  return React.createElement("h" + props.level, { id: slug }, props.children);
};

export function useMDXComponents(components: MDXComponents): MDXComponents {
  return {
    // Custom link component
    a: ({ href, children }) => {
      if (href) {
        if (href.startsWith("/") || href.startsWith("#"))
          return <Link href={href}>{children}</Link>;
      }

      return (
        <Link href={href as string} target="_blank" rel="noopener noreferrer">
          {children}
        </Link>
      );
    },
    h1: ({ children }) => (
      <HeadingRenderer level={1}>{children}</HeadingRenderer>
    ),
    h2: ({ children }) => (
      <HeadingRenderer level={2}>{children}</HeadingRenderer>
    ),
    h3: ({ children }) => (
      <HeadingRenderer level={3}>{children}</HeadingRenderer>
    ),
    h4: ({ children }) => (
      <HeadingRenderer level={4}>{children}</HeadingRenderer>
    ),
    h5: ({ children }) => (
      <HeadingRenderer level={5}>{children}</HeadingRenderer>
    ),
    h6: ({ children }) => (
      <HeadingRenderer level={6}>{children}</HeadingRenderer>
    ),
    ...components,
  };
}

function findHeadings

import React from "react";

type HeadingType = {
  depth: string;
  text: React.ReactNode;
  id: string;
};

const isHeading = (child: React.ReactElement): boolean => {
  return ["h1", "h2", "h3", "h4", "h5", "h6"].includes(child.type as string);
};

export const findHeadings = (
  children: React.ReactNode,
  depth: number = 0
): HeadingType[] => {
  return React.Children.toArray(children).reduce(
    (headings: HeadingType[], child) => {
      if (React.isValidElement(child)) {
        // Check if the element itself is a heading
        if (isHeading(child)) {
          const heading: HeadingType = {
            depth: child.type as string,
            text: child.props.children,
            id: child.props.id || "",
          };
          return [...headings, heading];
        }
        // Recursively check children of the current element
        if (child.props && child.props.children) {
          return [
            ...headings,
            ...findHeadings(child.props.children, depth + 1),
          ];
        }
      }
      return headings;
    },
    []
  );
};

MdxLayout.tsx

"use client";

import React, { useState } from "react";
import { findHeadings } from "@/utils/markdown";
import Link from "next/link";

type MdxLayoutProps = {
  children: React.ReactNode;
};

const MdxLayout: React.FC<MdxLayoutProps> = ({ children }) => {
  const [headings] = useState(findHeadings(children));

  return (
    <div className="relative flex items-start gap-x-16">
      {/* Content */}
      <div className="flex-1">
        <article className="mx-auto prose lg:prose-xl">{children}</article>
      </div>
      {/* Link */}
      <nav className="hidden w-60 shrink-0 lg:block sticky top-0">
        <ul className="">
          {headings.map((heading, i) => (
            <li key={i}>
              <Link
                href={`#${heading.id}`}
                className=""
              >
                <span>{heading.text}</span>
              </Link>
            </li>
          ))}
        </ul>
      </nav>
    </div>
  );
};
export default MdxLayout;

Finally, wrap your MDX content with the MdxLayout component in your page.mdx files. :)

[don-esteban]

It would be great if you describe in plain text what your code does. Motivation/use case/gains. Not everybody is willing to read code before evaluating relevance. Thanks!