@bundt/dxdocs

Beautiful documentation sites from MDX. Zero client JavaScript, pure static HTML.

Status: Pre-release (0.1.0). Core build pipeline, dev server, theme system, and all built-in components are implemented.

Install

bun add @bundt/dxdocs

Quickstart

Create a docs directory and config:

mkdir docs

---
title: Welcome
---

# Hello World

Your first documentation page.

// dxdocs.config.ts
export default {
  title: 'My Docs',
  navigation: [
    { type: 'page', path: '/', title: 'Home' }
  ]
};

Start the dev server:

bunx dxdocs dev

Build for production:

bunx dxdocs build

Output lands in ./dist/ — deploy to any static host (S3, CloudFront, Vercel, Netlify, GitHub Pages).

Features

• Zero runtime JS — Pre-rendered static HTML with no framework shipped to the browser
• MDX-first — Markdown with embedded React components, processed at build time
• Syntax highlighting — Shiki with 11 language grammars out of the box
• Light & dark themes — Automatic OS preference detection (prefers-color-scheme) or forced mode
• Table of contents — Auto-generated from h2/h3 headings with scroll-spy tracking
• Live reload — Dev server (via chokidar) with instant refresh on file changes
• Fast builds — Powered by Bun for sub-second static generation
• Built-in components — Callout, Card, CardGrid, Steps, and Step
• Nested navigation — Pages and groups with arbitrary nesting depth
• Header links — GitHub and external links with icon support
• Custom theming — Accent color and dark mode strategy via config
• GFM support — GitHub Flavored Markdown (tables, strikethrough, task lists) enabled by default
• Configurable extensions — .md and .mdx by default, extensible

Configuration

// dxdocs.config.ts
export default {
  // Site metadata
  title: 'My Project',           // Default: 'DXDocs'
  description: 'Project docs',   // Default: ''
  base: '/',                     // URL base path
  logo: './logo.svg',            // Optional logo image
  favicon: './favicon.svg',      // Optional favicon

  // Navigation structure (pages and nested groups)
  navigation: [
    { type: 'page', path: '/', title: 'Home' },
    {
      type: 'group',
      title: 'Guides',
      items: [
        { type: 'page', path: '/install', title: 'Installation' },
        { type: 'page', path: '/usage', title: 'Usage' },
        {
          type: 'group',
          title: 'Advanced',
          items: [
            { type: 'page', path: '/advanced/theming', title: 'Theming' }
          ]
        }
      ]
    }
  ],

  // Header links (top-right)
  headerLinks: [
    { label: 'GitHub', href: 'https://github.com/you/repo', icon: 'github' },
    { label: 'API', href: 'https://api.example.com', icon: 'external' }
  ],

  // Theme configuration
  theme: {
    accentColor: '#7c3aed',     // CSS color for accent elements
    darkMode: 'media'           // 'media' (OS preference) | 'light' | 'dark'
  },

  // MDX processing
  mdx: {
    extensions: ['.md', '.mdx'], // File extensions to process
    gfm: true                    // GitHub Flavored Markdown
  },

  // Output
  output: {
    outDir: './dist'             // Build output directory
  }
};

The configuration schema is validated with Zod 4 at load time — invalid configs produce clear error messages.

Built-in Components

All components are available automatically in MDX files without imports.

Callout

Four variants with icons (via Lucide):

<Callout variant="info">Important information here.</Callout>
<Callout variant="tip">A helpful suggestion.</Callout>
<Callout variant="warning">Proceed with caution.</Callout>
<Callout variant="error">Something went wrong.</Callout>

Card & CardGrid

Link cards with optional icons, arranged in a responsive grid:

<CardGrid>
  <Card title="Getting Started" href="/getting-started">
    Quick setup guide for new users
  </Card>
  <Card title="API Reference" href="/api">
    Complete API documentation
  </Card>
</CardGrid>

Cards support internal links (/path), external links (https://...), or no link (static card).

Steps

Ordered step-by-step instructions:

<Steps>
  <Step title="Install">Run `bun add @bundt/dxdocs`</Step>
  <Step title="Configure">Create `dxdocs.config.ts`</Step>
  <Step title="Write">Add MDX files to `docs/`</Step>
</Steps>

CLI

dxdocs dev              # Start dev server with live reload
dxdocs build            # Build static site to output directory

Project Structure

my-project/
├── docs/
│   ├── index.mdx              # Homepage
│   ├── getting-started.mdx
│   └── api/
│       ├── overview.mdx
│       └── reference.mdx
├── public/                     # Static assets (copied to output)
├── dxdocs.config.ts            # Site configuration
└── package.json

Architecture

apps/dxdocs/
  src/
    cli.ts                CLI entry (dev, build commands via cac)
    index.ts              Library entry

    config/
      loader.ts           Config file discovery and loading
      schema.ts           Zod 4 config schema with defaults

    mdx/
      compiler.ts         MDX -> React element compilation (via @mdx-js/mdx)
      components.tsx      Built-in component definitions (Callout, Card, Steps, etc.)

    build/
      builder.ts          Static site builder (MDX compile -> React SSR -> HTML)
      dev.ts              Dev server with chokidar file watching
      shared.ts           Shared utilities (page resolution, asset copying)

    theme/
      layout.tsx          Page layout component (sidebar, TOC, header, content)
      tokens.ts           CSS custom property generation from config
      styles.css          Complete theme stylesheet (light + dark)

Styling

dxdocs uses BEM-style CSS classes prefixed with void- (the internal theme name). The theme supports light and dark modes via CSS custom properties and prefers-color-scheme media queries.

To customize colors, set theme.accentColor in your config. For deeper customization, the generated HTML uses semantic class names that you can override with your own CSS.

Requirements

• Bun v1.3+

Runtime Limitation

dxdocs requires Bun as its runtime. The CLI, dev server, and build pipeline use Bun-specific APIs (Bun.serve(), Bun.file(), Bun.Glob) that have no Node.js equivalents.

If you install via npm/yarn and run with Node, the CLI shim will detect Bun is missing and offer to install it interactively. Once available, the shim delegates to Bun automatically.

Peer Dependencies

dxdocs declares its heavy dependencies as peer deps to allow version deduplication:

• @mdx-js/mdx ^3.1.0
• react / react-dom ^19.1.0
• shiki ^3.0.0
• zod ^4.0.0
• gray-matter, remark-gfm, lucide-react, unist-util-visit

License

MIT