Performance Optimization

BunPress is built for speed. This guide covers optimization techniques for even better performance.

Build Performance

Parallel Processing

BunPress builds pages in parallel by default:

export default {
  build: {
    parallel: true,
    workers: 4, // Number of worker threads
  },
}

Incremental Builds

Only rebuild changed files:

bunpress build --incremental

Asset Optimization

Image Optimization

export default {
  build: {
    images: {
      optimize: true,
      formats: ['webp', 'avif'],
      quality: 80,
      lazy: true,
    },
  },
}

CSS Optimization

export default {
  build: {
    css: {
      minify: true,
      purge: true, // Remove unused CSS
      inline: true, // Inline critical CSS
    },
  },
}

JavaScript Optimization

export default {
  build: {
    js: {
      minify: true,
      treeshake: true,
      split: true, // Code splitting
    },
  },
}

Content Optimization

Markdown Caching

export default {
  markdown: {
    cache: true,
  },
}

Syntax Highlighting

Preload common languages:

export default {
  markdown: {
    syntaxHighlighting: {
      preloadLanguages: ['typescript', 'javascript', 'bash'],
      lazy: true, // Lazy load other languages
    },
  },
}

Search Index

Build search index at build time:

export default {
  search: {
    prebuilt: true,
    lazy: true, // Load on demand
  },
}

CDN and Caching

Static Assets

export default {
  build: {
    assets: {
      hash: true, // Add content hash to filenames
      maxAge: 31536000, // 1 year cache
    },
  },
}

CDN Configuration

export default {
  build: {
    base: 'https://cdn.example.com/',
    assetPrefix: 'https://cdn.example.com/assets/',
  },
}

Compression

Gzip/Brotli

export default {
  build: {
    compress: {
      gzip: true,
      brotli: true,
    },
  },
}

Pre-compress Assets

bunpress build --compress

Benchmarking

Markdown Engine Performance

BunPress uses Bun's built-in Zig-based markdown parser (Bun.markdown), which is significantly faster than all JavaScript-based alternatives. All engines are configured with equivalent GFM features (tables, strikethrough, task lists, autolinks) for a fair comparison. These results were measured 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 (@mdit-vue/plugin-headers, @mdit-vue/plugin-sfc, @mdit-vue/plugin-component) on top of markdown-it. Real Astro adds Shiki on top of remark/rehype. commonmark.js does not support GFM (no tables, strikethrough, or task lists), so it processes fewer features and appears artificially fast.

Engines tested:

• BunPress - Bun.markdown (Zig-based, built into Bun) with full GFM
• VitePress - markdown-it + task-lists plugin (JS, as configured in VitePress)
• Eleventy - markdown-it + task-lists plugin (JS, default engine + GFM parity)
• Astro - remark + remark-gfm + rehype (JS, unified ecosystem)
• marked - JS, fast compiler (GFM enabled by default)
• micromark - JS, small + safe + CommonMark (with GFM extension)
• showdown - JS, bidirectional converter (with GFM options)
• commonmark (no GFM) - JS, reference CommonMark impl (NO GFM support)

Simple Markdown (paragraph + inline formatting)

Inline-Heavy Content (~3KB)

Headings

Lists (unordered, ordered, task lists)

GFM Tables

Code Blocks

Mixed Content (realistic doc page)

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:

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

Running Benchmarks

# Markdown engine benchmarks (self-contained)
cd benchmark && bun install && bun run bench

# All benchmarks (build, server, features)
cd benchmark && bun run bench:all

Build Time

bunpress build --profile

Page Speed

bunpress analyze

Monitoring

Build Stats

export default {
  build: {
    stats: true,
    statsFile: './build-stats.json',
  },
}

Bundle Analysis

bunpress build --analyze

Best Practices

Optimize Images

1. Use WebP/AVIF formats
2. Specify dimensions
3. Use lazy loading
4. Responsive images

![Alt text](/image.webp){width=800 height=600 loading=lazy}

Minimize JavaScript

1. Defer non-critical scripts
2. Use async loading
3. Tree-shake unused code
4. Split by route

Optimize CSS

1. Purge unused styles
2. Inline critical CSS
3. Defer non-critical CSS
4. Minify in production

Content Best Practices

1. Keep pages focused
2. Lazy load heavy content
3. Use appropriate heading levels
4. Optimize code examples

Performance Checklist

• Enable build caching
• Optimize images
• Minify CSS/JS
• Enable compression
• Configure CDN
• Preload critical assets
• Lazy load non-critical content
• Enable prefetching
• Monitor build times
• Analyze bundle size

Lighthouse Score

Target scores:

Related

• Configuration - Build options
• CI/CD Integration - Deployment optimization
• Theming - CSS optimization