Render MDX and TOC

Leadtype does not render your website. Your docs app owns MDX runtime components, layout, accessibility, and the "On this page" UI. Leadtype defines the contracts that keep the rendered HTML and generated markdown aligned.

Register MDX components

Use the component names Leadtype's remark stack knows how to flatten:

import { mdxComponents } from '@/components/docs-mdx';

export const components = {
  ...mdxComponents,
};

The naming contract is documented in Components. If your app uses different component names, add a custom remark plugin that maps them back before Leadtype flattens MDX to markdown.

Use the same heading slugs

resolveDocsNavigation extracts a table of contents from page headings. Your rendered headings need matching id attributes or sidebar links will miss.

Import slugifyDocsHeading from the fs-free readability entry point:

import { slugifyDocsHeading } from 'leadtype/llm/readability';
import { type ComponentPropsWithoutRef, isValidElement } from 'react';

type HeadingProps = ComponentPropsWithoutRef<'h1'>;

function textFromChildren(children: unknown): string {
  if (typeof children === 'string' || typeof children === 'number') {
    return String(children);
  }
  if (Array.isArray(children)) {
    return children.map(textFromChildren).join('');
  }
  if (isValidElement(children)) {
    const elementProps = children.props as { children?: unknown };
    return textFromChildren(elementProps.children);
  }
  return '';
}

function createHeading(level: 1 | 2 | 3 | 4 | 5 | 6) {
  return ({ children, id, ...props }: HeadingProps) => {
    const Component = `h${level}` as const;
    const headingId = id ?? slugifyDocsHeading(textFromChildren(children));
    return (
      <Component id={headingId || undefined} {...props}>
        {children}
      </Component>
    );
  };
}

Authors can still pin an anchor by passing an explicit id.

Generate navigation with TOC data

resolveDocsNavigation includes toc on every page. The default range is h2 to h3.

import { resolveDocsNavigation } from 'leadtype/llm';
import docsConfig from '../docs/docs.config';

const navigation = await resolveDocsNavigation({
  srcDir: '.',
  baseUrl: 'https://example.com',
  groups: docsConfig.groups,
  toc: { minLevel: 2, maxLevel: 4 },
});

Write the navigation object to a generated JSON file and import it from your sidebar.

Render the sidebar

Look up the current page in the manifest and pass currentPage.toc to your sidebar component. The example app includes a complete React implementation with scroll-spy, hash sync, active highlighting, and sticky positioning:

apps/example/src/components/table-of-contents.tsx

Troubleshooting

• TOC links do not scroll anywhere. Your heading IDs do not match the extracted slugs. Use slugifyDocsHeading in the rendered heading components.
• A page TOC is empty. All headings are outside the configured minLevel and maxLevel range. Defaults exclude h1 and headings deeper than h3.
• Sidebar order differs from llms.txt. The app is not using the same docs.config.ts groups as the generation step.