Migrating from VitePress

This guide helps you migrate an existing VitePress documentation site to BunPress.

Why Migrate

BunPress offers several advantages:

• 11x faster builds - 0.18s vs 1.93s for 4,000 files
• Native Bun runtime - No Node.js dependency
• VitePress-compatible - Similar configuration and markdown syntax
• Lighter footprint - Smaller bundle sizes

Quick Migration

1. Install BunPress

# Remove VitePress
npm uninstall vitepress
# or
bun remove vitepress

# Install BunPress
bun add -D @stacksjs/bunpress

2. Update Configuration

Rename your config file:

mv docs/.vitepress/config.ts bunpress.config.ts

Update the configuration format:

VitePress (before):

// docs/.vitepress/config.ts
import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'My Docs',
  description: 'Documentation for my project',

  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Guide', link: '/guide/' },
    ],
    sidebar: {
      '/guide/': [
        { text: 'Introduction', link: '/guide/' },
      ],
    },
  },
})

BunPress (after):

// bunpress.config.ts
import type { BunPressOptions } from '@stacksjs/bunpress'

export default {
  docsDir: './docs',
  outDir: './dist',

  nav: [
    { text: 'Home', link: '/' },
    { text: 'Guide', link: '/guide/' },
  ],

  markdown: {
    title: 'My Docs',
    meta: {
      description: 'Documentation for my project',
    },

    sidebar: {
      '/guide/': [
        { text: 'Introduction', link: '/guide/' },
      ],
    },
  },
} satisfies BunPressOptions

3. Update package.json Scripts

Before:

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  }
}

After:

{
  "scripts": {
    "docs:dev": "bunpress dev",
    "docs:build": "bunpress build",
    "docs:preview": "bunpress preview"
  }
}

4. Move Content (Optional)

If your docs are in a subdirectory:

# Keep existing structure (BunPress supports ./docs by default)
# Or move to project root if preferred

Configuration Mapping

Theme Config

Site Config

Markdown Config

Feature Compatibility

Fully Compatible

These features work identically:

• Markdown syntax (CommonMark + GFM)
• Custom containers (::: tip, ::: warning, etc.)
• GitHub alerts (> [!NOTE], > [!TIP], etc.)
• Code groups
• Line highlighting in code blocks
• Code diffs (// [!code ++], // [!code --])
• Frontmatter (YAML)
• Table of Contents
• Emoji shortcodes

Slightly Different

Home Page Layout:

VitePress:

---
layout: home
hero:
  name: My Project
  text: Fast & Simple
  tagline: Get started quickly
  actions:

    - theme: brand

      text: Get Started
      link: /guide/
---

BunPress: Same syntax (compatible)

Code Import:

VitePress: <<< @/snippets/code.ts BunPress: <<< ./snippets/code.ts

Different Implementation

Vue Components:

VitePress uses Vue components. BunPress uses HTML/Markdown:

<!-- VitePress -->
<script setup>
import CustomComponent from './components/Custom.vue'
</script>

<CustomComponent />

<!-- BunPress -->
Use HTML directly or markdown includes:
<!--@include: ./partials/custom.md-->

Content Migration

Move Documentation Files

# If using .vitepress/docs structure
mv docs/.vitepress/theme ./archive/  # Archive Vue theme
mv docs/.vitepress/cache ./archive/  # Remove cache

# Keep markdown files in docs/
# They're compatible without changes

Update Internal Links

Most links work unchanged. Check for:

<!-- VitePress-specific paths -->
[Link](/guide/index.md)  <!-- Works in both -->
[Link](/guide/)          <!-- Works in both -->

Update Image Paths

<!-- Both support -->
![Image](/images/logo.png)      <!-- From docs/public/images/ -->
![Image](./images/local.png)    <!-- Relative path -->

Theme Migration

Custom CSS

VitePress:

/* docs/.vitepress/theme/custom.css */
:root {
  --vp-c-brand: #646cff;
  --vp-c-brand-light: #747bff;
}

BunPress:

// bunpress.config.ts
export default {
  markdown: {
    themeConfig: {
      colors: {
        primary: '#646cff',
      },
      css: `
        :root {
          --bp-primary-light: #747bff;
        }
      `,
    },
  },
}

Custom Components

For Vue components, convert to:

1. Markdown includes for content
2. HTML with CSS for styling
3. Client-side JavaScript for interactivity

SEO Migration

Meta Tags

VitePress:

export default {
  head: [
    ['meta', { name: 'theme-color', content: '#646cff' }],
    ['link', { rel: 'icon', href: '/favicon.ico' }],
  ],
}

BunPress:

export default {
  markdown: {
    meta: {
      'theme-color': '#646cff',
    },
    // Favicon: place in docs/public/
  },
}

Sitemap

VitePress:

import { defineConfig } from 'vitepress'

export default defineConfig({
  sitemap: {
    hostname: 'https://example.com',
  },
})

BunPress:

export default {
  sitemap: {
    enabled: true,
    baseUrl: 'https://example.com',
  },
}

Analytics Migration

Google Analytics to Fathom

VitePress typically uses gtag. BunPress recommends privacy-focused Fathom:

export default {
  fathom: {
    enabled: true,
    siteId: 'YOUR*SITE*ID',
    honorDNT: true,  // Privacy-friendly
  },
}

Deployment

BunPress generates static files compatible with the same hosts:

• Netlify
• Vercel
• GitHub Pages
• Cloudflare Pages

Build Command

# VitePress
vitepress build docs

# BunPress
bunpress build

Output Directory

# VitePress default
docs/.vitepress/dist/

# BunPress default
dist/

Update deployment config if needed:

# netlify.toml
[build]
  command = "bunpress build"
  publish = "dist"

Troubleshooting

Common Issues

1. Missing styles

Ensure CSS is configured:

markdown: {
  themeConfig: {
    colors: { primary: '#3b82f6' },
  },
}

2. Broken navigation

Check path format:

// Include leading slash
{ text: 'Guide', link: '/guide/' }

3. Missing sidebar

Ensure correct path matching:

sidebar: {
  '/guide/': [  // Match URL path exactly
    // ...
  ],
}

4. Code highlighting issues

Set the theme explicitly:

markdown: {
  syntaxHighlightTheme: 'github-dark',
}

Getting Help

• Check BunPress documentation
• Compare with VitePress docs
• File issues on GitHub

Migration Checklist

• Install BunPress, remove VitePress
• Convert config file format
• Update package.json scripts
• Test all pages render correctly
• Verify navigation works
• Check code highlighting
• Test search functionality
• Verify SEO (sitemap, robots.txt)
• Update CI/CD configuration
• Test production build
• Deploy and verify

Related

• Getting Started
• Configuration Guide
• CLI Reference