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:

  • Instant builds: Up to 10x faster than Node.js-based generators
  • 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' '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' '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-4wke8p2n4">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-4wke8p2n4', 0)">JavaScript</button><button class="code-group-tab " onclick="switchCodeTab('code-group-4wke8p2n4', 1)">TypeScript</button><button class="code-group-tab " onclick="switchCodeTab('code-group-4wke8p2n4', 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="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> 'Hello World'
<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></code></pre>
</div>
<div class="code-group-panel " data-panel="1">
  <pre data-lang="typescript"><code class="language-typescript"><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> 'Hello World'
<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></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' 'My Documentation',
  description:'Comprehensive project documentation' 'Comprehensive project documentation',

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

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

Advanced Code Block Features

Code Diff Markers

Highlight additions and deletions in code:

function greet(name) {

console.log('Hello ' + name) // [!code --]

console.log(Hello ${name}) // [!code ++]

}

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:

// Normal code

function setup() {

initializeApp() // [!code focus]

connectDatabase() // [!code focus]

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:

function process(data) {

const result = data.map(x => x * 2)

console.log(ressult) // [!code error]

return result; // [!code warning]

}

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' 'https://docs.example.com',
    defaultChangefreq:'monthly' 'monthly',
    priorityMap: {'/'
      '/': 1.0,'/guide/*'
      '/guide/*': 0.8,
    },
    exclude: ['/drafts/*''/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' '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' 'https://cdn.usefathom.com/script.js',
    defer: true,
    canonical:'https://docs.example.com' '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' 'development',
  markdown: {
    title: process.env.SITE_TITLE ||'My Documentation' 'My Documentation',
    description: process.env.SITE_DESCRIPTION ||'Documentation site' 'Documentation site'
  },
  sitemap: {
    enabled: process.env.ENABLE_SITEMAP ==='true' 'true',
    baseUrl: process.env.SITE_URL ||'https://example.com' 'https://example.com'
  },
  fathom: {
    enabled: process.env.ENABLE_ANALYTICS ==='true' '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' './bunpress.config'

Internationalization (i18n)

BunPress supports multiple languages for documentation:

// bunpress.config.ts
export default {
  i18n: {
    locales: ['en''en','es' 'es','fr' 'fr','de' 'de'],
    defaultLocale:'en' 'en',
    localePath:'./locales' './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''en','es' 'es','fr' 'fr'],
    defaultLocale:'en' 'en',
    detectLocale: true,          // Auto-detect from browser
    fallbackLocale:'en' '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''en','es' 'es'],
    defaultLocale:'en' 'en',
    localeConfig: {
      en: {
        title:'Documentation' 'Documentation',
        description:'Comprehensive documentation' 'Comprehensive documentation'
      },
      es: {
        title:'Documentación' 'Documentación',
        description:'Documentación completa' '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 (100 markdown files):

Metric BunPress VitePress Docusaurus Hugo
Build Time ~500ms ~2.5s ~8s ~300ms
Dev Startup ~100ms ~800ms ~3s ~50ms
Bundle Size ~45KB ~120KB ~250KB ~10KB
Memory Usage ~50MB ~150MB ~300MB ~30MB
Hot Reload <100ms ~200ms ~500ms ~100ms

BunPress is:

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

Performance Benchmarks

What's Next?

BunPress continues to evolve with new features in development:

Check out our roadmap for upcoming features and improvements.