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 with its native Zig-based markdown parser:

• 6.2x faster markdown parsing than VitePress on real-world documents
• 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:

::: tip
Helpful advice and best practices
:::

::: warning
Important warnings and cautions
:::

::: danger
Critical information requiring immediate attention
:::

::: info
General informational notes
:::

::: details
Collapsible content sections
:::

GitHub Alerts

Modern alert syntax for attention-grabbing callouts:

> [!NOTE]
> Essential information for users

> [!TIP]
> Helpful advice for better outcomes

> [!IMPORTANT]
> Critical information for success

> [!WARNING]
> Urgent attention required

> [!CAUTION]
> Potential risks and negative outcomes

Key Differences from Containers:

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

Code Highlighting & Features

Syntax Highlighting

Powered by ts-syntax-highlighter with support for multiple 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-821c1e732b8e">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-821c1e732b8e', 0)">JavaScript</button><button class="code-group-tab" onclick="switchCodeTab('code-group-821c1e732b8e', 1)">TypeScript</button><button class="code-group-tab" onclick="switchCodeTab('code-group-821c1e732b8e', 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=""> </span><span class="token source-js" style="">greeting</span><span class="token source-js" style=""> </span><span class="token keyword-operator-js" style="color: #cf222e">=</span><span class="token source-js" style=""> </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=""> </span><span class="token source-ts" style="">greeting</span><span class="token keyword-operator-ts" style="color: #cf222e">:</span><span class="token source-ts" style=""> </span><span class="token storage-type-ts" style="color: #cf222e">string</span><span class="token source-ts" style=""> </span><span class="token keyword-operator-ts" style="color: #cf222e">=</span><span class="token source-ts" style=""> </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"><span class="token source-python" style="">greeting</span><span class="token source-python" style=""> </span><span class="token keyword-operator-python" style="color: #cf222e">=</span><span class="token source-python" style=""> </span><span class="token string-quoted-double-python" style="color: #0a3069">&quot;Hello World&quot;</span></span>
<span class="line"><span class="token support-function-builtin-python" style="color: #8250df">print</span><span class="token source-python" style="">(</span><span class="token source-python" style="">greeting</span><span class="token source-python" style="">)</span></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 :heart: BunPress! :rocket:

This feature is :fire:!

Renders as: I ❤️ BunPress! 🚀

Popular Shortcodes:

• :heart: → ❤️
• :fire: → 🔥
• :rocket: → 🚀
• :star: → ⭐
• :thumbsup: → 👍
• :tada: → 🎉
• :warning: → ⚠️
• :check: → ✅

Inline Badges

Highlight important information with inline badges:

Available in <Badge type="tip" text="v2.0+" />

<Badge type="warning" text="deprecated" />
<Badge type="danger" text="breaking change" />
<Badge type="info" text="experimental" />

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

Navigation & Discovery

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 <!-- toc-ignore -->

Positions:

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

Search

Full-text search across all documentation:

• Fast client-side search
• Keyboard shortcuts
• Result highlighting
• Fuzzy matching support

Site Navigation

• 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
• sidebar: Set to false to render the page without the sidebar
• navbar: Set to false to hide the nav bar
• editLink: Set to false to hide the edit link on this page
• lastUpdated: true to show the last modified date, false to hide it, or an ISO date to state it explicitly

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 <figure> and <figcaption>
• 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
• FATHOM*SITE*ID - 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 publishes a documentation site in several languages, with translations loaded by ts-i18n.

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

The default locale is served at the site root and every other locale under its own prefix — /guide is English, /es/guide is Spanish. A site with a single locale, or no i18n block at all, renders exactly as before.

Localized Content

Put each language's pages in a directory named for the locale:

docs/
  guide.md          # en (the default locale)
  es/
    guide.md        # /es/guide
  fr/
    guide.md        # /fr/guide

Or suffix individual files, which is handier when only a few pages are translated:

docs/
  guide.md          # en
  guide.es.md       # /es/guide
  guide.fr.md       # /fr/guide

Both layouts work, and you can mix them. A page that a locale has not translated falls back to the default locale's copy, so adding a language never produces broken links.

Translation Files

UI strings — the search placeholder, the page outline heading — come from translation files. localePath follows the ts-i18n layout, so YAML, JSON and TypeScript all work:

locales/
  en/
    ui.yml
  es/
    ui.yml

# locales/es/ui.yml
search:
  placeholder: Buscar en la documentación
toc:
  title: En esta página

Keys may sit at the root of a locale file or under a namespace — ui.yml above resolves as both search.placeholder and ui.search.placeholder. Anything you do not translate keeps its English default.

Available keys:

Locale Detection

Send first-time visitors to the language their browser asks for:

export default {
  i18n: {
    locales: ['en', 'es', 'fr'],
    defaultLocale: 'en',
    detectLocale: true,
    fallbackLocale: 'en',
  },
}

Detection is deliberately conservative: it runs only at the default locale's root, only once per browser, and any manual switch is remembered so it never overrides a reader who chose a language on purpose.

Per-locale Configuration

Override configuration for a specific locale — typically the title, description or navigation:

export default {
  i18n: {
    locales: ['en', 'es'],
    defaultLocale: 'en',
    localeNames: { en: 'English', es: 'Español' },
    localeConfig: {
      es: {
        title: 'Documentación',
        description: 'Documentación completa',
      },
    },
  },
}

localeNames labels the locale switcher that appears in the nav bar; without it the switcher shows the locale codes.

What you get:

• URL structure: /es/guide, /fr/api
• A locale switcher in the nav bar
• <html lang> set per locale
• hreflang alternates for every locale (needs sitemap.baseUrl)
• Search scoped to the language being read
• Per-locale title, description, nav and sidebar
• Fallback to the default locale for untranslated pages

Performance Metrics

Markdown Engine Benchmarks

BunPress uses Bun's built-in Zig-based markdown parser, which dominates all JavaScript-based alternatives. All engines configured with equivalent GFM features (tables, strikethrough, task lists, autolinks). Tested on Apple M3 Pro, 18GB RAM, Bun 1.3.10, using mitata.

Fairness note: These results are conservative. Real VitePress adds Shiki syntax highlighting + Vue plugins on top of markdown-it. Real Astro adds Shiki on top of remark/rehype. commonmark.js does not support GFM, so it processes fewer features and appears artificially fast.

Real-World Doc Page (~3KB markdown)

Large Document Stress Test (~33KB markdown)

Throughput: 100 Mixed Documents

Build Performance (4,000 markdown files)

Using the same methodology as 11ty's official performance tests:

Fast Mode (Simple Markdown to HTML)

Full-Featured Build (with syntax highlighting, templates, TOC)

Output File Size

Summary

BunPress is:

• 6.2x faster markdown parsing than VitePress on real-world documents
• 4.4x fasterthan Eleventy,90x faster than Astro on real-world docs
• 231x faster than marked on large documents
• 11x faster builds than Eleventy (4,000 files)
• 4x smaller output than VitePress
• The fastest documentation generator available
• Results are conservative: real VitePress/Astro add Shiki + extra plugins (even slower)

Run the benchmarks yourself:

cd benchmark && bun install && bun run bench

Feature Comparison

Containers vs GitHub Alerts

Code Imports vs Markdown Includes

Browser Support

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

Performance Benchmarks

• Markdown parsing: 6.2x faster than VitePress, 4.4x faster than Eleventy, 90x faster than Astro
• Build speed: 11x faster than Eleventy, 130x faster than Astro
• Throughput: 22,000+ markdown files per second
• Large documents: 6.8x faster than VitePress, 231x faster than marked on 33KB files
• 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.