BunPress Documentation
⌘ K
GuideAPIExamples

Features Overview

BunPress is a powerful static site generator with extensive markdown processing capabilities. This document provides a comprehensive overview of all available features.

Core Features

Lightning-Fast Performance

Built on Bun runtime for exceptional speed:

  • Fastest builds: 11x faster than Eleventy, 130x faster than Astro (4,000 files in 0.18s)
  • 22,000+ files/second: Industry-leading throughput for markdown processing
  • Hot module replacement: See changes instantly during development
  • Optimized bundling: Efficient code splitting and minification
  • Zero-config: Works out of the box with sensible defaults

Advanced Markdown Processing

Standard Markdown Support

Full CommonMark and GitHub-Flavored Markdown support:

  • Headings, paragraphs, lists
  • Tables, blockquotes, horizontal rules
  • Links, images, inline code
  • Task lists and strikethrough

Custom Containers

Create visually distinct content blocks:

<div class="custom-block tip">
  <p class="custom-block-title">TIP</p>
  <div class="custom-block-content">
    <p>Helpful advice and best practices</p>
  </div>
</div>


<div class="custom-block warning">
  <p class="custom-block-title">WARNING</p>
  <div class="custom-block-content">
    <p>Important warnings and cautions</p>
  </div>
</div>


<div class="custom-block danger">
  <p class="custom-block-title">DANGER</p>
  <div class="custom-block-content">
    <p>Critical information requiring immediate attention</p>
  </div>
</div>


<div class="custom-block info">
  <p class="custom-block-title">INFO</p>
  <div class="custom-block-content">
    <p>General informational notes</p>
  </div>
</div>


<details class="custom-block details">
  <summary>Details</summary>
  <div class="custom-block-content">
    <p>Collapsible content sections</p>
  </div>
</details>

GitHub Alerts

Modern alert syntax for attention-grabbing callouts:

<div class="github-alert github-alert-note">
  <p class="github-alert-title">
    <svg class="github-alert-icon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>
    Note
  </p>
  <div class="github-alert-content">
    <p>Essential information for users</p>
  </div>
</div>

<div class="github-alert github-alert-tip">
  <p class="github-alert-title">
    <svg class="github-alert-icon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z"></path></svg>
    Tip
  </p>
  <div class="github-alert-content">
    <p>Helpful advice for better outcomes</p>
  </div>
</div>

<div class="github-alert github-alert-important">
  <p class="github-alert-title">
    <svg class="github-alert-icon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>
    Important
  </p>
  <div class="github-alert-content">
    <p>Critical information for success</p>
  </div>
</div>

<div class="github-alert github-alert-warning">
  <p class="github-alert-title">
    <svg class="github-alert-icon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>
    Warning
  </p>
  <div class="github-alert-content">
    <p>Urgent attention required</p>
  </div>
</div>

<div class="github-alert github-alert-caution">
  <p class="github-alert-title">
    <svg class="github-alert-icon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>
    Caution
  </p>
  <div class="github-alert-content">
    <p>Potential risks and negative outcomes</p>
  </div>
</div>

Key Differences from Containers:

  • More semantic HTML structure
  • Distinctive icon indicators
  • GitHub-compatible syntax
  • Better accessibility support

Code Highlighting & Features

Syntax Highlighting

Powered by Shiki with support for 40+ languages:

// Full TypeScript support with type inference
interface Config {
  port: number
  host: string
}

const config: Config = {
  port: 3000,
  host: 'localhost'
}

Line Numbers

1function calculateSum(numbers: number[]): number {
2  return numbers.reduce((sum, num) => sum + num, 0)
3}

Line Highlighting

Highlight specific lines for emphasis:

function processData(data: string[]) {
  // This line is highlighted
  if (!data.length) return []

  // These lines are highlighted
  return data
    .filter(item => item.length > 0)
    .map(item => item.trim())
}

File Information

Show file paths in code blocks:

export const config = {
  apiUrl: 'https://api.example.com',
  timeout: 5000
}

Copy-to-Clipboard

Every code block includes a copy button with visual feedback:

  • Hover to reveal copy button
  • Click to copy entire code block
  • Visual confirmation on successful copy
  • Fallback for older browsers

Code Groups

Tabbed code blocks for multiple examples:

<div class="code-group" id="code-group-7n4sv2mum">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-7n4sv2mum', 0)">JavaScript</button><button class="code-group-tab " onclick="switchCodeTab('code-group-7n4sv2mum', 1)">TypeScript</button><button class="code-group-tab " onclick="switchCodeTab('code-group-7n4sv2mum', 2)">Python</button>
  </div>
  <div class="code-group-panels">
    <div class="code-group-panel active" data-panel="0">
  <pre data-lang="javascript"><code class="language-javascript"><span class="line"><span class="token storage-type-js" style="color: #cf222e">const</span> <span class="token source-js" style="">greeting</span> <span class="token keyword-operator-js" style="color: #cf222e">=</span> <span class="token string-quoted-double-js" style="color: #0a3069">&#039;Hello World&#039;</span></span>
<span class="line"><span class="token source-js" style="">console</span><span class="token keyword-operator-js" style="color: #cf222e">.</span><span class="token entity-name-function-js" style="color: #8250df">log</span><span class="token source-js" style="">(</span><span class="token source-js" style="">greeting</span><span class="token source-js" style="">)</span></span>
<span class="line"></span></code></pre>
</div>
<div class="code-group-panel " data-panel="1">
  <pre data-lang="typescript"><code class="language-typescript"><span class="line"><span class="token storage-type-ts" style="color: #cf222e">const</span> <span class="token source-ts" style="">greeting</span><span class="token keyword-operator-ts" style="color: #cf222e">:</span> <span class="token storage-type-ts" style="color: #cf222e">string</span> <span class="token keyword-operator-ts" style="color: #cf222e">=</span> <span class="token string-quoted-double-ts" style="color: #0a3069">&#039;Hello World&#039;</span></span>
<span class="line"><span class="token source-ts" style="">console</span><span class="token keyword-operator-ts" style="color: #cf222e">.</span><span class="token entity-name-function-ts" style="color: #8250df">log</span><span class="token source-ts" style="">(</span><span class="token source-ts" style="">greeting</span><span class="token source-ts" style="">)</span></span>
<span class="line"></span></code></pre>
</div>
<div class="code-group-panel " data-panel="2">
  <pre data-lang="python"><code class="language-python"><span class="line">greeting = &quot;Hello World&quot;</span>
<span class="line">print(greeting)</span>
<span class="line"></span></code></pre>
</div>
  </div>
</div>

Features:

  • Tab navigation between code samples
  • Independent syntax highlighting per tab
  • Compatible with line numbers and highlighting
  • Supports all programming languages

Code Imports

Import code directly from source files to keep documentation in sync with your codebase.

Full File Import

<<< ./examples/server.ts

Imports the entire file with automatic language detection.

Line Range Import

<<< ./examples/api.ts{10-25}

Import specific line ranges to focus on relevant sections.

Named Region Import

<<< ./src/app.ts{#setup}

Import code between region markers:

// #region setup
const app = express()
app.use(cors())
app.use(express.json())
// #endregion setup

Benefits:

  • Always up-to-date code examples
  • Single source of truth for documentation
  • Reduced documentation maintenance
  • Syntax highlighting preserved
  • Error handling for missing files

Markdown File Inclusion

Reuse markdown content across multiple pages.

Full File Inclusion

<!--@include: ./components/intro.md-->

Partial Inclusion

Line Ranges:

<!--@include: ./guide.md{1-50}-->

Named Regions:

<!--@include: ./docs/auth.md{#overview}-->

With region markers in the source file:

<!-- #region overview -->
## Authentication Overview

Content here...
<!-- #endregion -->

Advanced Features:

  • Recursive includes (included files can include others)
  • Circular reference protection
  • Full markdown processing of included content
  • Relative path resolution
  • Graceful error handling

Use Cases:

  • Shared content across documentation
  • Modular documentation structure
  • Version-specific content management
  • Multi-language documentation

Typography Enhancements

Emoji Support

Use shortcodes for easy emoji insertion:

I ❤️ BunPress! 🚀

This feature is 🔥!

Renders as: I ❤️ BunPress! 🚀

Popular Shortcodes:

  • ❤️ → ❤️
  • 🔥 → 🔥
  • 🚀 → 🚀
  • ⭐ → ⭐
  • 👍 → 👍
  • 🎉 → 🎉
  • ⚠️ → ⚠️
  • :check: → ✅

Inline Badges

Highlight important information with inline badges:

Available in <span class="badge badge-tip" style="display: inline-block; padding: 2px 8px; font-size: 0.85em; font-weight: 600; border-radius: 4px; background: #dcfce7; color: #14532d; border: 1px solid #22c55e; margin: 0 4px; vertical-align: middle;">v2.0+</span>

<span class="badge badge-warning" style="display: inline-block; padding: 2px 8px; font-size: 0.85em; font-weight: 600; border-radius: 4px; background: #fef3c7; color: #78350f; border: 1px solid #f59e0b; margin: 0 4px; vertical-align: middle;">deprecated</span>
<span class="badge badge-danger" style="display: inline-block; padding: 2px 8px; font-size: 0.85em; font-weight: 600; border-radius: 4px; background: #fee2e2; color: #7f1d1d; border: 1px solid #ef4444; margin: 0 4px; vertical-align: middle;">breaking change</span>
<span class="badge badge-info" style="display: inline-block; padding: 2px 8px; font-size: 0.85em; font-weight: 600; border-radius: 4px; background: #e0f2fe; color: #0c4a6e; border: 1px solid #0ea5e9; margin: 0 4px; vertical-align: middle;">experimental</span>

Badge Types:

  • tip - Green for new features and recommendations
  • warning - Yellow for deprecations and cautions
  • danger - Red for breaking changes and critical warnings
  • info - Blue for general information

Use Cases:

  • Version indicators
  • Feature status (beta, stable, deprecated)
  • Breaking change warnings
  • API stability markers

Table of Contents

Automatic TOC generation from headings:

<!--INLINE_TOC_PLACEHOLDER-->

Features:

  • Automatic slug generation
  • Nested hierarchy support
  • Configurable depth levels (h1-h6)
  • Active section highlighting
  • Smooth scrolling navigation
  • Exclude specific headings with

Positions:

  • Sidebar: Floating navigation panel
  • Inline: Embedded in page content
  • Floating: Fixed position overlay

Full-text search across all documentation:

  • Fast client-side search
  • Keyboard shortcuts
  • Result highlighting
  • Fuzzy matching support
  • Navbar: Top-level navigation with dropdowns
  • Sidebar: Hierarchical documentation structure
  • Breadcrumbs: Page hierarchy visualization
  • Prev/Next: Sequential page navigation

Content Organization

Frontmatter

YAML frontmatter for page metadata:

---
title: Getting Started
description: Learn how to use BunPress
layout: doc
---

Supported Fields:

  • title: Page title
  • description: Meta description for SEO
  • layout: Page layout (home, doc, page)
  • hero: Hero section configuration
  • features: Feature grid for home layout
  • sidebar: Custom sidebar configuration
  • toc: Table of contents settings
  • editLink: Source file edit link
  • lastUpdated: Show last modified date

Home Page Layout

Create beautiful landing pages:

---
layout: home
hero:
  name: BunPress
  text: Lightning-fast documentation
  tagline: Build beautiful docs in seconds
  actions:
    - theme: brand
      text: Get Started
      link: /install
    - theme: alt
      text: View on GitHub
      link: https://github.com/stacksjs/bunpress
features:
  - title: Fast
    details: Built on Bun for exceptional performance
  - title: Flexible
    details: Extensive markdown extensions and customization
  - title: Simple
    details: Zero-config with sensible defaults
---

Developer Experience

Development Server

Fast development server with hot reload:

bun dev
# Server starts at http://localhost:3000

Features:

  • Instant hot module replacement
  • Error overlay
  • Source maps
  • Automatic page reload
  • Custom port configuration

Build System

Optimized production builds:

bun run build

Optimization:

  • Code minification
  • Asset optimization
  • Code splitting
  • Tree shaking
  • CSS purging

TypeScript Support

Full TypeScript support throughout:

  • Type-safe configuration
  • Typed plugins and themes
  • IntelliSense support
  • Strict mode compliance

SEO & Performance

SEO Features

  • Auto-generated meta tags
  • Semantic HTML structure
  • Sitemap generation
  • Robots.txt support
  • Open Graph tags
  • Twitter Card support
  • Canonical URLs

Performance Optimizations

  • Lazy loading for images
  • Code splitting by route
  • Minimal runtime overhead
  • Efficient CSS delivery
  • Optimized asset loading

Extensibility

Plugin System

Extend BunPress with custom plugins:

export default {
  plugins: [
    customPlugin(),
    anotherPlugin({
      // options
    })
  ]
}

Theme Customization

Full control over appearance:

  • Custom CSS
  • Theme overrides
  • Component replacement
  • Layout customization

Configuration

Flexible configuration via bunpress.config.ts:

export default {
  title: 'My Documentation',
  description: 'Comprehensive project documentation',

  themeConfig: {
    nav: [...],
    sidebar: {...},
    search: {...},
    footer: {...}
  },

  markdown: {
    toc: {...},
    highlighting: {...}
  }
}

Advanced Code Block Features

Code Diff Markers

Highlight additions and deletions in code:

```javascript
function greet(name) {
  console.log('Hello ' + name)
  console.log(`Hello ${name}`)
}
```

Output:

  • Lines with // [!code ++] show green background with + indicator
  • Lines with // [!code --] show red background with - indicator

Code Focus

Focus attention on specific code sections:

```javascript
// Normal code
function setup() {
  initializeApp()
  connectDatabase()
  startServer()
}
```

Output:

  • Focused lines highlighted with blue background
  • Non-focused lines dimmed with blur effect
  • Hover to reveal dimmed content

Error & Warning Markers

Mark problematic code lines:

```javascript
function process(data) {
  const result = data.map(x => x * 2)
  console.log(ressult)
  return result;
}
```

Output:

  • Error lines: Red background with ✕ icon
  • Warning lines: Yellow background with ⚠ icon

Table Enhancements

Column Alignment

| Left | Center | Right |
| :--- | :---: | ---: |
| Text | Text | Text |

Features:

  • Left align: :---
  • Center align: :---:
  • Right align: ---:
  • Mixed alignment in same table

Enhanced Styling

  • Striped rows (alternating colors)
  • Hover effects on rows
  • Responsive wrapper for wide tables
  • Horizontal scrolling on mobile
  • Enhanced borders and spacing

Image Enhancements

Image Captions

![Alt text](./image.png "Caption text")

Output:

<figure class="image-figure">
  <img src="./image.png" alt="Alt text" loading="lazy" decoding="async">
  <figcaption>Caption text</figcaption>
</figure>

Features:

  • Semantic HTML with
    and
  • Automatic lazy loading
  • Async decoding for performance
  • Styled captions (italic, gray, centered)

Lazy Loading

All images automatically get:

  • loading="lazy" attribute
  • decoding="async" attribute
  • Preserved alt text for accessibility

CLI Tools

BunPress includes 15+ CLI commands for managing your documentation:

Core Commands

bunpress init              # Initialize new project
bunpress dev               # Start dev server
bunpress build             # Build for production
bunpress preview           # Preview production build

Content Management

bunpress new <path>        # Create new markdown file
  --title "Page Title"     # Custom title
  --template guide         # Use template (default, guide, api, blog)

Maintenance

bunpress clean             # Remove build artifacts
bunpress stats             # Show documentation statistics
bunpress doctor            # Run diagnostic checks
bunpress llm               # Generate LLM-friendly markdown
  --full                   # Include full content

Configuration

bunpress config:show       # Display configuration
bunpress config:validate   # Validate configuration
bunpress config:init       # Create new config file

SEO

bunpress seo:check         # Check SEO health
  --fix                    # Auto-fix issues

See CLI Reference for complete documentation.

SEO Features

XML Sitemap

Automatic sitemap.xml generation with:

  • Last modification dates
  • Change frequency configuration
  • Priority settings per path
  • URL exclusion patterns
  • Sitemap index for large sites (50,000+ URLs)
    • export default {
  sitemap: {
    enabled: true,
    baseUrl: 'https://docs.example.com',
    defaultChangefreq: 'monthly',
    priorityMap: {
      '/': 1.0,
      '/guide/*': 0.8,
    },
    exclude: ['/drafts/*']
  }
}

Robots.txt

Configurable robots.txt with:

  • Multi-agent rules
  • Allow/disallow patterns
  • Crawl-delay directives
  • Automatic sitemap linking

Meta Tags

Automatically generated for every page:

  • Title and description
  • Open Graph tags for social sharing
  • Twitter Card tags
  • Canonical URLs
  • Viewport and charset tags

Open Graph Tags

Rich social media previews:

  • og:type - Content type
  • og:url - Page URL
  • og:title - Page title
  • og:description - Page description
  • og:image - Social card image (1200x630)
  • og:site_name - Site name

Twitter Cards

Enhanced Twitter previews:

  • twitter:card - Card type (summarylargeimage)
  • twitter:title - Tweet title
  • twitter:description - Tweet description
  • twitter:image - Preview image

Structured Data (JSON-LD)

Three schema types automatically generated:

TechArticle Schema:

{
  "@context": "https://schema.org",
  "@type": "TechArticle",
  "headline": "Page Title",
  "description": "Page description",
  "datePublished": "2024-01-15",
  "dateModified": "2024-10-29"
}

Breadcrumb Schema:

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [...]
}

WebSite Schema:

{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "Site Name",
  "url": "https://example.com"
}

RSS Feeds

Generate RSS feeds for blog-style documentation:

  • Date-based sorting
  • Configurable max items
  • Full content or excerpts
  • Author attribution
  • Auto description extraction

SEO Validation

Built-in CLI validator:

bunpress seo:check

Checks:

  • ✓ All pages have titles (10-60 characters)
  • ✓ All pages have descriptions (50-160 characters)
  • ✓ No duplicate titles
  • ✓ No broken internal links
  • ✓ All images have alt text

Auto-fix:

bunpress seo:check --fix

See SEO Guide for complete documentation.

Analytics Integration

Fathom Analytics

Privacy-focused analytics with GDPR/CCPA compliance:

export default {
  fathom: {
    enabled: true,
    siteId: 'YOUR_SITE_ID',

    // Privacy options
    honorDNT: true,          // Honor Do Not Track
    auto: true,              // Auto tracking
    spa: false,              // SPA mode

    // Advanced options
    scriptUrl: 'https://cdn.usefathom.com/script.js',
    defer: true,
    canonical: 'https://docs.example.com'
  }
}

Features:

  • No cookies
  • GDPR/CCPA compliant
  • Do Not Track support
  • Lightweight script (~1KB)
  • Real-time analytics
  • Custom events support

See Configuration Guide for details.

Environment Variables

BunPress supports environment variables for dynamic configuration:

// bunpress.config.ts
export default {
  verbose: process.env.NODE_ENV === 'development',
  markdown: {
    title: process.env.SITE_TITLE || 'My Documentation',
    description: process.env.SITE_DESCRIPTION || 'Documentation site'
  },
  sitemap: {
    enabled: process.env.ENABLE_SITEMAP === 'true',
    baseUrl: process.env.SITE_URL || 'https://example.com'
  },
  fathom: {
    enabled: process.env.ENABLE_ANALYTICS === 'true',
    siteId: process.env.FATHOM_SITE_ID
  }
}

Common Environment Variables:

  • NODE_ENV - Environment mode (development/production)
  • SITE_TITLE - Site title
  • SITE_DESCRIPTION - Site description
  • SITE_URL - Base URL for sitemap and canonical links
  • ENABLE_SITEMAP - Toggle sitemap generation
  • ENABLE_ANALYTICS - Toggle analytics
  • FATHOMSITEID - Fathom Analytics site ID

Using .env files:

# .env
NODE_ENV=production
SITE_TITLE=My Awesome Docs
SITE_URL=https://docs.example.com
ENABLE_SITEMAP=true
FATHOM_SITE_ID=ABCDEFGH

Load with your favorite .env loader (e.g., dotenv or Bun's native support):

// Load .env file (Bun does this automatically)
import { config } from './bunpress.config'

Internationalization (i18n)

BunPress supports multiple languages for documentation:

// bunpress.config.ts
export default {
  i18n: {
    locales: ['en', 'es', 'fr', 'de'],
    defaultLocale: 'en',
    localePath: './locales'
  }
}

Localized Content

Create locale-specific markdown files:

<!-- docs/intro.en.md -->
# Introduction
Welcome to our documentation!

<!-- docs/intro.es.md -->
# Introducción
¡Bienvenido a nuestra documentación!

<!-- docs/intro.fr.md -->
# Introduction
Bienvenue dans notre documentation !

<!-- docs/intro.de.md -->
# Einführung
Willkommen zu unserer Dokumentation!

Locale Detection

BunPress can automatically detect user locale:

export default {
  i18n: {
    locales: ['en', 'es', 'fr'],
    defaultLocale: 'en',
    detectLocale: true,          // Auto-detect from browser
    fallbackLocale: 'en'         // Fallback if locale not found
  }
}

Translation Files

Structure your translations:

locales/
├── en/
│   ├── common.json
│   └── navigation.json
├── es/
│   ├── common.json
│   └── navigation.json
└── fr/
    ├── common.json
    └── navigation.json

Example translation file:

{
  "nav": {
    "home": "Home",
    "guide": "Guide",
    "api": "API Reference",
    "examples": "Examples"
  },
  "toc": {
    "title": "On This Page"
  },
  "search": {
    "placeholder": "Search documentation..."
  }
}

Per-locale Configuration

Override configuration for specific locales:

export default {
  i18n: {
    locales: ['en', 'es'],
    defaultLocale: 'en',
    localeConfig: {
      en: {
        title: 'Documentation',
        description: 'Comprehensive documentation'
      },
      es: {
        title: 'Documentación',
        description: 'Documentación completa'
      }
    }
  }
}

Features:

  • Multiple language support
  • Automatic locale detection
  • Translation file management
  • Per-locale configuration
  • Fallback locale support
  • URL structure: /es/guide, /fr/api, etc.

    • Note

    i18n support is currently in development. Full internationalization features are planned for a future release.

Performance Metrics

Real benchmark data using 11ty's methodology with 4,000 markdown files:

Build Time Benchmark

Fast Mode (Simple Markdown to HTML)

Comparable to Eleventy's approach - pure markdown processing without syntax highlighting:

Generator Build Time Files/Second vs BunPress
BunPress 0.18s 22,714 -
Eleventy 1.93s 2,073 11x slower
VitePress 8.5s 471 47x slower
Astro 22.90s 175 130x slower
Gatsby 29.05s 138 165x slower
Next.js 70.65s 57 401x slower

Full Mode (With Syntax Highlighting, Templates, TOC)

Complete feature set comparable to VitePress/Astro:

Generator Build Time Files/Second vs BunPress
BunPress 4.12s 972 -
VitePress 8.5s 471 2x slower
Astro 22.90s 175 5.6x slower
Gatsby 29.05s 138 7x slower
Next.js 70.65s 57 17x slower

Output File Size Benchmark

Comparison of typical documentation page output sizes (includes HTML, CSS, and JavaScript):

Framework Size (KB) vs BunPress Savings
BunPress 45 - -
Astro 65 1.4x larger 31%
VitePress 180 4x larger 75%
Docusaurus 220 4.9x larger 80%
Next.js 250 5.6x larger 82%

Why BunPress output is smaller:

  • Minimal JavaScript (CSS-first interactivity)
  • No framework runtime (no Vue, React, or Svelte)
  • Optimized inline styles
  • Server-rendered, no hydration needed

Summary

BunPress is:

  • 11x faster than Eleventy in comparable mode
  • 2x faster than VitePress with full features
  • 5.6x faster than Astro with full features
  • 17x faster than Next.js in all modes
  • 4x smaller output than VitePress
  • The fastest documentation generator available

Run the benchmark yourself:

bun test test/benchmark.test.ts

Feature Comparison

Containers vs GitHub Alerts

Feature Containers GitHub Alerts
Syntax ::: type > [!TYPE]
GitHub Compatible ❌ ✅
Collapsible ✅ (details) ❌
Icons Basic Distinctive
Semantic HTML Good Better
Use Case VitePress-style GitHub-style

Code Imports vs Markdown Includes

Feature Code Imports Markdown Includes
Syntax <<<
Content Type Source code Markdown
Syntax Highlighting ✅ ✅ (in result)
Line Ranges ✅ ✅
Named Regions ✅ ✅
Recursive ❌ ✅
Language Detection Auto N/A

Browser Support

  • Modern browsers: Full feature support
  • Progressive enhancement: Graceful degradation
  • Accessibility: WCAG compliant markup
  • Mobile responsive: Optimized for all screen sizes

Performance Benchmarks

  • Build speed: 11x faster than Eleventy, 130x faster than Astro
  • Throughput: 22,000+ markdown files per second
  • Page load: Sub-second initial load
  • Hot reload: < 100ms update time
  • Search: Instant client-side results

What's Next?

BunPress continues to evolve with new features in development:

  • Enhanced theming system
  • Advanced search with filters
  • Multi-language i18n support
  • Interactive components
  • Version documentation support
  • And much more!

Check out our roadmap for upcoming features and improvements.

Copy page
Copy page as Markdown for LLMs
View as Markdown
View this page as plain text
Open in ChatGPT
Copy content and open ChatGPT
Open in Claude
Copy content and open Claude
Open in Perplexity
Search with Perplexity AI