External Pages

Boltdocs lets you register custom React pages that live outside the MDX pipeline. This is useful for landing pages, fully custom layouts, or pages that need client-side interactivity beyond what Markdown offers.

Defining Pages

In pages-external/index.tsx, export a pages object mapping URL paths to React components:

import HomePage from '../../src/pages/home-page'

export const pages = {
  '/': HomePage,
  '/custom': MyCustomPage,
}

Custom Layout

You can also export a layout function to wrap all external pages:

import { Navbar, Sidebar } from 'boltdocs/client'
import HomePage from '../../src/pages/home-page'

export const pages = {
  '/': HomePage,
}

export const layout = ({ children }: { children: React.ReactNode }) => (
  <div className="min-h-screen">
    <Navbar />
    <div className="flex">
      <Sidebar />
      <main className="flex-1 p-8">
        {children}
      </main>
    </div>
  </div>
)

Full Example

Here's a complete pages-external/index.tsx with landing page and custom layout:

import { Navbar, Sidebar, SearchDialog } from 'boltdocs/client'
import LandingPage from '../../src/pages/landing-page'
import PricingPage from '../../src/pages/pricing-page'

export const pages = {
  '/': LandingPage,
  '/pricing': PricingPage,
}

export const layout = ({ children }: { children: React.ReactNode }) => (
  <div className="min-h-screen bg-white dark:bg-zinc-900">
    <Navbar />
    <SearchDialog />
    {children}
  </div>
)

Using Boltdocs Components

External pages can import any component exported from boltdocs/client:

import { Navbar, Sidebar, SearchDialog, Breadcrumbs } from 'boltdocs/client'

This gives you access to the same UI primitives used in the default docs layout.

Static File Routing (experimental)

For literal pages you can enable file-based external routing instead of maintaining a pages object. Configure experimental.fileRouting in boltdocs.config.ts:

export default defineConfig({
  experimental: {
    fileRouting: true,
  },
})

docs/pages-external/
├── home.tsx      → /home
├── about.tsx     → /about
└── pricing.mdx   → /pricing

The file name becomes the route. .tsx, .ts, .jsx, .js, .mdx, and .md are supported. index.* stays reserved for the legacy pages object. Dynamic segments like [id], groups like (marketing), and reserved helper files (layout, icons, and mdx-components) are ignored. Existing pages-external/index.tsx routes can coexist with file routes; avoid mapping the same URL in both APIs.

Localized Files

When i18n is configured, a top-level directory whose name matches a configured locale provides the localized version of a page — the same convention docs content uses (docs/es/…):

docs/pages-external/
├── roadmap.mdx      → /roadmap        (default locale)
└── es/
    └── roadmap.mdx  → /es/roadmap     (Spanish)

Each locale URL is served with the localized file when it exists, and otherwise with the default locale file — just like docs i18n fallback routes. For React components that translate internally (e.g., with useI18n()), the fallback is sufficient: switching languages re-renders the default component with the active locale derived from the URL. Create a localized .tsx file only when you need a truly distinct component per language.

Directories that don't match a configured locale remain literal URL segments (guides/start.mdx → /guides/start).

See Static file routing for the full opt-in API.

Limitations

• External pages do not support MDX features like <Callout> or <Card>
• Frontmatter is not available — all metadata must be handled in React
• External page indexing behavior depends on project-generated route metadata; add explicit metadata when you need searchable headings

When to Use External Pages

Jesús Alcalá

Last updated on October 18, 2026