Add in-page quick-nav

Author: Brijesh Bittu

docs/package.json

@@ -18,6 +18,7 @@
     "@stefanprobst/rehype-extract-toc": "^2.2.1",
     "clipboard-copy": "4.0.1",
     "clsx": "^2.1.1",
+    "estree-util-value-to-estree": "^3.3.2",
     "hast-util-to-string": "^3.0.1",
     "next": "15.1.6",
     "react": "^19.0.0",

docs/src/components/ContentPage.tsx

@@ -1,4 +1,4 @@
-import { mdxComponents } from 'docs/mdx-components';
+import { useMDXComponents } from 'docs/mdx-components';
 import { readMarkdown } from 'docs/utils/mdx';
 import { notFound } from 'next/navigation';
 
@@ -7,5 +7,6 @@ export default async function ContentPage({ basePath, slug }: { basePath: string
   if (!MdxContent) {
     return notFound();
   }
-  return <MdxContent components={mdxComponents} />;
+  const components = useMDXComponents();
+  return <MdxContent components={components} />;
 }

docs/src/components/QuickNav.pigment.ts

@@ -14,7 +14,7 @@ export const Root = styled.nav(({ theme }) => ({
   $quickNavItemLineHeight: t('$text.md.lineHeight'),
   $quickNavItemPaddingY: 'calc($quickNavItemHeight / 2 - $quickNavItemLineHeight / 2)',
   /* The variable is used in JS positioning logic */
-  $top: -1,
+  $top: '-1px',
   $marginTop: '5.75rem' /* Match hero code block top */,
   ...applyText(theme, 'md'),
   zIndex: 1,

docs/src/mdx-components.tsx

@@ -1,13 +1,19 @@
 import * as React from 'react';
-import type { MDXComponents } from 'mdx/types';
+import type { MDXComponents as BaseMdxComponents } from 'mdx/types';
 
 import * as CodeBlock from './components/CodeBlock';
 import * as Styled from './mdx-components.pigment';
+import * as QuickNav from './components/QuickNav';
 import { Link } from './components/Link';
 import { getChildrenText } from './utils/getChildrenText';
 import { Changelog } from './components/Changelog';
 import { LinkIcon } from './icons/LinkIcon';
 
+interface MDXComponents {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  [key: string]: React.FC<any> | MDXComponents;
+}
+
 export const mdxComponents: MDXComponents = {
   a: (props) => <Link {...props} />,
   h1: (props) => (
@@ -58,20 +64,18 @@ export const mdxComponents: MDXComponents = {
     return <meta {...props} />;
   },
   Changelog,
-  LinkIcon: (props) => {
-    console.log(props);
-    return <LinkIcon width={16} />;
-  },
+  LinkIcon: () => <LinkIcon width={16} />,
+  QuickNav,
 };
 
 export const inlineMdxComponents: MDXComponents = {
   ...mdxComponents,
   p: (props) => <p {...props} />,
 };
 
-export function useMDXComponents(comp: MDXComponents): MDXComponents {
+export function useMDXComponents(comp: MDXComponents = {}) {
   return {
     ...comp,
     ...mdxComponents,
-  };
+  } as BaseMdxComponents;
 }

docs/src/utils/mdx.tsx

@@ -13,6 +13,7 @@ import rehyeAutolinkHeading from 'rehype-autolink-headings';
 
 import { rehypeSubtitle } from './rehype/rehypeSubtitle';
 import { rehypeInlineCode } from './rehype/rehypeInlineCode';
+import { rehypeQuickNav } from './rehype/rehypeQuickNav';
 
 const theme: Theme = {
   name: 'pigment-css',
@@ -361,8 +362,8 @@ export async function renderMdx(mdxSource: string) {
           },
         },
       ],
-      // rehypeAutoLinkContent,
       rehypeExtractToc,
+      rehypeQuickNav,
       rehypeSubtitle,
       rehypeInlineCode,
     ],

docs/src/utils/rehype/createMdxElement.ts

@@ -0,0 +1,60 @@
+// @ts-check
+import { valueToEstree } from 'estree-util-value-to-estree';
+
+export function createMdxElement({
+  name,
+  children,
+  props = {},
+}: {
+  name: string;
+  children: unknown[];
+  props?: Record<string, unknown>;
+}) {
+  // Native HTML elements are rendered as regular tags
+  if (name.toLowerCase() === name) {
+    return {
+      type: 'element',
+      tagName: name,
+      properties: props,
+      children,
+    };
+  }
+
+  return {
+    type: 'mdxJsxFlowElement',
+    name,
+    attributes: Object.entries(props).map(([key, value]) => ({
+      type: 'mdxJsxAttribute',
+      name: key,
+      value: getAttributeValue(value),
+    })),
+    data: { _mdxExplicitJsx: true },
+    children,
+  };
+}
+
+/**
+ * @param {unknown} value
+ */
+function getAttributeValue(value: unknown) {
+  if (typeof value === 'string') {
+    return value;
+  }
+
+  return {
+    type: 'mdxJsxAttributeValueExpression',
+    value: JSON.stringify(value),
+    data: {
+      estree: {
+        type: 'Program',
+        body: [
+          {
+            type: 'ExpressionStatement',
+            expression: valueToEstree(value),
+          },
+        ],
+        sourceType: 'module',
+      },
+    },
+  };
+}

docs/src/utils/rehype/rehypeAutoLinkContent.ts

@@ -1,14 +1,6 @@
 import { visitParents } from 'unist-util-visit-parents';
-import type { evaluate } from '@mdx-js/mdx';
+import { Pluggable } from './rehypeSubtitle';
 
-export type Pluggable = Exclude<
-  Parameters<typeof evaluate>[1]['rehypePlugins'],
-  undefined | null
->[number];
-
-/**
- * Unwrap potential paragraphs inside `<Subtitle>`
- */
 export const rehypeAutoLinkContent: Pluggable = () => {
   return (tree) => {
     visitParents(tree, (node) => {

docs/src/utils/rehype/rehypeQuickNav.ts

@@ -0,0 +1,67 @@
+import { TocEntry } from '@stefanprobst/rehype-extract-toc';
+import { Pluggable } from './rehypeSubtitle';
+import { createMdxElement } from './createMdxElement';
+
+const ROOT = 'QuickNav.Root';
+const TITLE = 'QuickNav.Title';
+const LIST = 'QuickNav.List';
+const ITEM = 'QuickNav.Item';
+const LINK = 'QuickNav.Link';
+
+export const rehypeQuickNav: Pluggable = () => {
+  return (tree, file) => {
+    const toc = file.data.toc;
+    if (!toc) {
+      return;
+    }
+    const root = createMdxElement({
+      name: ROOT,
+      children: toc.flatMap(getNodeFromEntry).filter(Boolean),
+    });
+
+    if (!toc.length) {
+      return;
+    }
+
+    tree.children.unshift(root);
+  };
+};
+
+function getNodeFromEntry({ value, depth, id, children }: TocEntry) {
+  const sub = createMdxElement({
+    name: LIST,
+    children: [],
+  });
+
+  // Ignore <h4>'s and below
+  if (depth < 3 && children?.length) {
+    sub.children = children.map(getNodeFromEntry);
+  }
+
+  if (depth === 1) {
+    // Insert "(Top)" link
+    sub.children?.unshift(getNodeFromEntry({ value: '(Top)', id: '', depth: 2 }));
+
+    return [
+      // Insert a top-level title
+      createMdxElement({
+        name: TITLE,
+        children: [{ type: 'text', value }],
+      }),
+      sub,
+    ];
+  }
+
+  const link = createMdxElement({
+    name: LINK,
+    children: [{ type: 'text', value }],
+    props: {
+      href: `#${id}`,
+    },
+  });
+
+  return createMdxElement({
+    name: ITEM,
+    children: [link, sub],
+  });
+}

packages/pigment-css-utils/src/theme.ts

@@ -2,8 +2,6 @@ import { serializeStyles } from '@emotion/serialize';
 import setWith from 'lodash/setWith';
 import { getCSSVar } from './utils/processStyle';
 
-import { getCSSVar } from './utils/processStyle';
-
 interface Theme extends Record<string, unknown> {}
 
 const PIGMENT_LAYERS = ['globals', 'utils', 'base', 'variants', 'compoundvariants', 'sx'];