feat(repo): add extractToc remark plugin for mobile table of contents

[NWylynko]

Description

Adds a remark plugin (extractToc) that extracts structured table of contents (TOC) data from markdown headings and injects it into YAML frontmatter. This is the data layer needed to support an expandable mobile TOC on the docs site.

Context: The table of contents for each docs page is currently hidden on mobile (DOCS-11605). To render an expandable mobile TOC, the docs rendering engine needs easy access to structured heading data. This plugin pre-computes that data during the build pipeline so the rendering engine doesn't need to re-parse the MDX.

What the plugin does

• Walks the markdown AST and extracts h2–h4 headings (configurable via minDepth/maxDepth)
• Supports custom heading IDs from MDX annotation syntax (## Heading {{ id: 'custom-id' }})
• Generates URL-safe slugs for anchor links
• Injects a structured toc array into the YAML frontmatter

Output format

toc:
  - title: "Getting Started"
    slug: "getting-started"
    level: 2
  - title: "Installation"
    slug: "installation"
    level: 3

Integration with clerk-docs build pipeline

This plugin is designed to be integrated into the clerk-docs build pipeline (scripts/build-docs.ts) as a remark plugin:

import { extractToc } from './extract-toc.mjs'

remark()
  .use(remarkFrontmatter)
  .use(remarkMdx)
  .use(remarkGfm)
  .use(extractToc())
  // ... other plugins
  .process(...)

Remaining work

After this plugin is integrated into clerk-docs, the rendering engine in clerk/clerk needs to:

1. Read the toc frontmatter field
2. Render a collapsible/expandable "On this page" section that appears on mobile viewports

Tests

16 unit tests covering:

• Slug generation (special chars, collapsing, trimming)
• TOC extraction from heading nodes (depth filtering, empty heading filtering, custom IDs)
• Full remark plugin integration (frontmatter injection, MDX support, depth options, quote escaping, missing frontmatter handling)

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• JSDoc comments have been added for all exports
• Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Linear Issue: DOCS-11605

  

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Apr 29, 2026 5:09pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4515bd4

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[NWylynko]

testing out cursor cloud agents started in linear - ran in the wrong repo 🤦