Skip to main content

MDX Content Pipeline

apps/web uses @next/mdx to render long-form content (currently: legal pages) from MDX files in apps/web/content/.

Pipeline​

next.config.ts wraps the Next config with createMDX({...}) and pipes:

  • remark-gfm — GitHub-flavoured markdown (tables, strikethrough, task lists).
  • rehype-slug — derives id attributes from heading text.
  • rehype-autolink-headings — appends an anchor link to each heading.

apps/web/mdx-components.tsx maps every MDX element (h2, p, table, blockquote, …) to Tailwind-styled React components using Lumio design tokens. No per-page overrides are needed — all legal pages inherit this mapping.

Current surface​

The MDX pipeline currently powers the six legal pages under /legal:

  • imprint
  • privacy
  • terms
  • cookies
  • security
  • faq

Adding a legal page​

  1. Add the slug to apps/web/src/components/legal/legal-pages.ts (pick an icon from lucide-react and set lastUpdated).
  2. Add MDX files at apps/web/content/en/legal/<slug>.mdx and apps/web/content/de/legal/<slug>.mdx.
  3. Add translation keys under legal.pages.<slug> in messages/en.json and messages/de.json (title, description, navLabel).
  4. Register the EN + DE loader entries in apps/web/src/lib/mdx-import.ts so the dynamic import() specifiers stay string literals (required for Next.js to statically bundle them).

The route /legal/<slug> is produced automatically by the dynamic legal/[slug]/page.tsx handler.

Fallback behaviour​

If /content/<locale>/legal/<slug>.mdx doesn't exist, importLegalMdx falls back to the English file. If the English file is also missing, the page calls notFound().

TOC generation​

rehype-slug sets heading IDs at build time. The LegalToc component (client) reads the rendered DOM and drives the "On this page" sidebar using an IntersectionObserver. No manual TOC authoring is needed.

Adding bigger styling changes​

All MDX typography lives in apps/web/mdx-components.tsx. Don't add Tailwind classes inside MDX body text — they'd apply to plain markdown as well and leak inconsistent styling.