Markdown pages

.md and .mdx files in src/routes are pages. They use the same layouts, middleware, loaders, actions, and SPA navigation as .tsx pages. The only difference is the page body is written in markdown.

src/routes/about.mdx            →  GET /about
src/routes/docs/index.md        →  GET /docs
src/routes/docs/index.server.tsx
src/routes/blog/[slug].mdx      →  GET /blog/:slug

A TypeScript page wins if both about.tsx and about.mdx exist.

Frontmatter and `toc`

YAML frontmatter and a heading table of contents are passed as props, together with any loader data.

src/routes/guide.mdx

---
title: Deploying
description: Ship the worker.
---

# Deploying

{props.description}

## Prerequisites

type GuideProps = {
  title: string;
  description: string;
  frontmatter: { title: string; description: string };
  toc: Array<{ id: string; text: string; depth: number; children?: GuideProps["toc"] }>;
};

Flattened frontmatter fields (title, description) sit next to loader props. Loader fields win on conflict.
frontmatter is the full object.
toc is a nested list of headings. Heading ids match the slugs rendered on the page (hello-world for ## Hello world). Use static heading text so the slug stays readable — # {props.title} becomes propstitle because the TOC is built from source.

Read them from a layout or island with the same hooks used for loader data:

src/routes/_layout.tsx

import type { ReactNode } from "react";
import { useFrontmatter, useToc } from "better-router/react";

export default function Layout({ children }: { children: ReactNode }) {
  const { title } = useFrontmatter<{ title?: string }>();
  const toc = useToc();
  return (
    <div>
      {title ? <p>{title}</p> : null}
      {toc.length > 0 ? (
        <ol>
          {toc.map((item) => (
            <li key={item.id}>
              <a href={`#${item.id}`}>{item.text}</a>
            </li>
          ))}
        </ol>
      ) : null}
      {children}
    </div>
  );
}

useLoaderData() also includes frontmatter and toc on markdown routes.

Layouts, middleware, loaders

Nothing else changes.

src/routes/guide.server.tsx

import type { LoaderArgs } from "better-router";

export function loader({ params }: LoaderArgs) {
  return { slug: params.slug };
}

export const middleware = async (c, next) => {
  await next();
};

src/routes/_layout.tsx, _layout.server.tsx, _middleware.ts, and src/middleware wrap markdown pages the same way they wrap JSX pages. Island files work too: notes.island.mdx.

MDX

.mdx can use JSX. Components from src/components/markdown are already in scope — do not import them. .md is markdown only (GFM tables, task lists, and strikethrough are on by default).

src/routes/docs/counter.mdx

# Interactive docs

<Counter />

Counter is the default export of src/components/markdown/Counter.tsx.

Markdown components

Default exports in src/components/markdown are registered automatically.

File	Used as
`src/components/markdown/h1.tsx`	`<h1>`
`src/components/markdown/code.tsx`	`<code>`
`src/components/markdown/Callout.tsx`	`<Callout>`
`src/components/markdown/wrapper.tsx`	MDX layout around the page body

src/components/markdown/Callout.tsx

import type { ReactNode } from "react";

export default function Callout({ children }: { children?: ReactNode }) {
  return <aside className="callout">{children}</aside>;
}

<Callout>You do not import this. The plugin maps the file name.</Callout>

Change the folder with markdown.componentsDir:

vite.config.ts

betterRouter({
  markdown: {
    componentsDir: "src/mdx-components",
  },
});

Plugins

Pass remark / rehype / recma plugins. remark-gfm and rehype-slug are already included.

vite.config.ts

import rehypeAutolinkHeadings from "rehype-autolink-headings";
import remarkToc from "remark-toc";
import { betterRouter } from "better-router/plugin";

export default defineConfig({
  plugins: [
    betterRouter({
      markdown: {
        remarkPlugins: [remarkToc],
        rehypePlugins: [rehypeAutolinkHeadings],
      },
    }),
  ],
});

Custom renderer (comark)

The default compiler is @mdx-js/mdx. Replace it when you want another engine. parse is the HTML path: return markup and we wrap it as a React page. Frontmatter and toc still become props.

vite.config.ts

import { parse as comark } from "comark";
import { defineConfig } from "vite";
import { betterRouter } from "better-router/plugin";

export default defineConfig({
  plugins: [
    betterRouter({
      markdown: {
        async parse(file) {
          const result = comark(file.content, {
            gfm: true,
            frontmatter: file.frontmatter,
          });
          return {
            html: result.html,
            frontmatter: result.frontmatter ?? file.frontmatter,
            toc: result.toc ?? file.toc,
          };
        },
      },
    }),
  ],
});

file is { id, filename, source, content, frontmatter, toc, format }. content is the body with YAML already stripped. compile replaces the whole module. Return JavaScript whose default export is a React component. Missing frontmatter / toc exports are filled in for you.

betterRouter({
  markdown: {
    async compile(file) {
      const html = renderWithComark(file.content);
      return `
        export default function Page(props) {
          return <article dangerouslySetInnerHTML={{ __html: ${JSON.stringify(html)} }} />;
        }
      `;
    },
  },
});

compile wins if both are set.

TypeScript

*.md / *.mdx default exports are typed as React pages with frontmatter and toc named exports. Add better-router/client to tsconfig compilerOptions.types or include client.d.ts as you already do for the other virtual modules.

Get started

Routing

Rendering

Deploy

Guides

Reference

Frontmatter and `toc`

Layouts, middleware, loaders

MDX

Markdown components

Plugins

Custom renderer (comark)

TypeScript

​Frontmatter and toc

​Layouts, middleware, loaders

​MDX

​Markdown components

​Plugins

​Custom renderer (comark)

​TypeScript

Frontmatter and `toc`

Layouts, middleware, loaders

MDX

Markdown components

Plugins

Custom renderer (comark)

TypeScript