@amamo/doctrine

Build an MDX directory into a static React documentation site. Doctrine provides a Vite development server, prerendered HTML, Pagefind search, localized navigation, light and dark themes, and subpath-safe assets without requiring a production Node.js server.

• Node.js 20.19 or newer.
• A native target supported by @amamo/mdx. Doctrine has no JavaScript fallback for MDX compilation.
• Trusted content and configuration authors. MDX, referenced TSX pages, config files, navigation files, and custom components can execute JavaScript during the build.

pnpm add @amamo/doctrine
mkdir docs

Create docs/index.mdx:

# My documentation

The first page is ready.

Create docs/meta.ts to make the page part of the navigation:

import { defineDirectory } from '@amamo/doctrine'

export default defineDirectory({
  items: [{ page: 'index', title: 'My documentation' }],
})

Preview and build:

pnpm exec doctrine dev docs
pnpm exec doctrine build docs --site-url https://example.com/project/

Development defaults to http://localhost:5173. Production output defaults to dist; pass the real public URL so assets, canonical links, locale routes, search results, and 404.html use the correct deployment base.

doctrine.config.ts is optional. Add it at the project root when the defaults are not enough:

import { defineConfig } from '@amamo/doctrine'

export default defineConfig({
  title: 'My project',
  description: 'Guides for My project.',
  githubUrl: 'https://github.com/acme/my-project',
  copyright: 'Copyright © 2026 Acme.',
  locales: {
    default: 'en',
    names: ['en', 'zh-CN'],
    labels: { en: 'English', 'zh-CN': '简体中文' },
  },
})

Locale variants use filename suffixes. Every directory with content for a locale also has the matching navigation module:

docs/index.mdx
docs/meta.ts
docs/index.zh-CN.mdx
docs/meta.zh-CN.ts
docs/guide/install.mdx
docs/guide/meta.ts
docs/guide/install.zh-CN.mdx
docs/guide/meta.zh-CN.ts

The default locale uses /guide/install/; the translated page uses /zh-CN/guide/install/. Navigation modules own page titles, icons, child directories, and order.

A page entry can also name a same-directory .tsx file. Only TSX files listed by the matching locale navigation module become routes; every other TSX file remains an ordinary component. These pages render inside Doctrine's header and footer without the documentation sidebar, prose layout, or table of contents.

CLI + doctrine.config.* + meta*.ts
  -> normalize paths, URLs, locales, and navigation
  -> Vite + @amamo/mdx compile content and client/SSR bundles
  -> React prerenders every navigation route
  -> Doctrine writes HTML, assets, and 404.html
  -> Pagefind indexes the final HTML

Doctrine keeps the generated content registry and cache records in .amamo-mdx/, and temporary build work in .doctrine/. Treat both as generated directories and keep them out of version control.

• Getting started
• Features and runtime behavior
• Customization
• Configuration
• CLI reference
• GitHub Pages deployment

See CONTRIBUTING.md to work on Doctrine itself.

MIT