Configuration

BunPress can be configured through a bunpress.config.ts file in your project root.

Basic Configuration

// bunpress.config.ts
export default {
  // Enable verbose logging
  verbose: true,

  // Markdown plugin configuration
  markdown: {
    title:'My Documentation' 'My Documentation',
    meta: {
      description:'My project documentation' 'My project documentation',
      author:'Your Name' 'Your Name',
    },
    scripts: ['/js/highlight.js'
      '/js/highlight.js',
    ],
  },
}

Available Options

General Options

Markdown Plugin Options

Navigation Configuration

Configure the navigation bar:

export default {
  nav: [
    { text:'Home' 'Home', link:'/' '/', icon:'🏠' '🏠' },
    {
      text:'Guide' 'Guide',
      activeMatch:'/guide' '/guide',
      items: [
        { text:'Getting Started' 'Getting Started', link:'/guide/getting-started' '/guide/getting-started' },
        { text:'Advanced' 'Advanced', link:'/guide/advanced' '/guide/advanced' }
      ]
    },
    { text:'API' 'API', link:'/api' '/api' },
    { text:'GitHub' 'GitHub', link:'https://github.com' 'https://github.com', icon:'🐙' '🐙' }
  ]
}

NavItem Properties

Sidebar Configuration

Configure the sidebar navigation:

export default {
  markdown: {
    sidebar: {'/'
      '/': [
        { text:'Home' 'Home', link:'/' '/' },
        {
          text:'Guide' 'Guide',
          items: [
            { text:'Getting Started' 'Getting Started', link:'/guide/getting-started' '/guide/getting-started' },
            { text:'Advanced' 'Advanced', link:'/guide/advanced' '/guide/advanced' }
          ]
        },
        { text:'API' 'API', link:'/api' '/api' }
      ]
    }
  }
}

SidebarItem Properties

Search Configuration

Configure search functionality:

export default {
  markdown: {
    search: {
      enabled: true,
      placeholder:'Search documentation...' 'Search documentation...',
      maxResults: 10,
      keyboardShortcuts: true
    }
  }
}

SearchConfig Properties

Theme Configuration

Customize the appearance of your documentation:

export default {
  markdown: {
    themeConfig: {
      colors: {
        primary:'#3b82f6' '#3b82f6',
        secondary:'#64748b' '#64748b',
        accent:'#f59e0b' '#f59e0b'
      },
      fonts: {
        heading:'Inter, sans-serif' 'Inter, sans-serif',
        body:'Roboto, sans-serif' 'Roboto, sans-serif',
        mono:'JetBrains Mono, monospace' 'JetBrains Mono, monospace'
      },
      darkMode: true,
      cssVars: {'border-radius'
        'border-radius':'8px' '8px','shadow'
        'shadow':'0 4px 6px -1px rgba(0, 0, 0, 0.1)' '0 4px 6px -1px rgba(0, 0, 0, 0.1)'
      }
    }
  }
}

ThemeConfig Properties

Colors

Fonts

Other Options

Default Metadata

By default, BunPress includes the following metadata:

{
  description:'Documentation built with BunPress' 'Documentation built with BunPress',
  generator:'BunPress' 'BunPress',
  viewport:'width=device-width, initial-scale=1.0' 'width=device-width, initial-scale=1.0',
}

Sitemap Configuration

Configure sitemap and SEO optimization:

export default {
  sitemap: {
    enabled: true,
    baseUrl:'https://example.com' 'https://example.com',
    filename:'sitemap.xml' 'sitemap.xml',
    defaultPriority: 0.5,
    defaultChangefreq:'monthly' 'monthly',
    exclude: ['/private/**''/private/**','/admin/**' '/admin/**'],
    priorityMap: {'/'
      '/': 1.0,'/docs/**'
      '/docs/**': 0.8,'/examples/**'
      '/examples/**': 0.6
    },
    changefreqMap: {'/blog/**'
      '/blog/**':'weekly' 'weekly','/docs/**'
      '/docs/**':'monthly' 'monthly'
    },
    maxUrlsPerFile: 50000,
    useSitemapIndex: false
  }
}

Robots.txt Configuration

Configure robots.txt for search engine crawling:

export default {
  robots: {
    enabled: true,
    filename:'robots.txt' 'robots.txt',
    rules: [
      {
        userAgent:'Googlebot' 'Googlebot',
        allow: ['/''/'],
        disallow: ['/private/''/private/','/admin/' '/admin/']
      },
      {
        userAgent:'Bingbot' 'Bingbot',
        allow: ['/''/'],
        disallow: ['/admin/''/admin/'],
        crawlDelay: 1
      }
    ],
    sitemaps: ['https://example.com/sitemap.xml''https://example.com/sitemap.xml'],
    host:'example.com' 'example.com'
  }
}

Fathom Analytics Configuration

BunPress supports Fathom Analytics - a privacy-focused analytics platform. The analytics script will be automatically injected into all pages when enabled.

Basic Setup

export default {
  fathom: {
    enabled: true,
    siteId:'ABCDEFGH' 'ABCDEFGH'  // Your Fathom site ID
  }
}

Full Configuration

export default {
  fathom: {
    // Enable/disable Fathom Analytics
    enabled: true,

    // Your Fathom site ID (required when enabled)
    // Find this in your Fathom dashboard
    siteId:'ABCDEFGH' 'ABCDEFGH',

    // Custom Fathom script URL (optional)// Default: 'https://cdn.usefathom.com/script.js'
    // Default: 'https://cdn.usefathom.com/script.js'
    scriptUrl:'https://cdn.usefathom.com/script.js' 'https://cdn.usefathom.com/script.js',

    // Load script with defer attribute (recommended)
    // Default: true
    defer: true,

    // Honor Do Not Track browser setting
    // Default: false
    honorDNT: false,

    // Canonical URL for the site (optional)
    // Overrides automatic canonical URL detection
    canonical:'https://example.com' 'https://example.com',

    // Enable auto tracking (tracks pageviews automatically)
    // Default: true
    auto: true,

    // Enable SPA (Single Page Application) mode
    // Default: false
    spa: false
  }
}

Configuration Options

Finding Your Fathom Site ID

1. Log in to your Fathom Analytics dashboard

2. Select your site from the dashboard

3. Go to Settings > Sites

4. Copy the Site ID (e.g., NXCLHKXQ)

5. Add it to your bunpress.config.ts

Privacy Features

Fathom Analytics is privacy-focused by design:

• No cookies - GDPR, CCPA, and PECR compliant
• No personal data - Only anonymized metrics
• No tracking across sites - Site-isolated analytics
• No fingerprinting - Respects user privacy

Advanced Usage

Single Page Application (SPA) Mode

If your documentation uses client-side routing (SPA), enable SPA mode:

export default {
  fathom: {
    enabled: true,
    siteId:'ABCDEFGH' 'ABCDEFGH',
    spa: true  // Automatically tracks route changes
  }
}

Do Not Track (DNT)

Respect users who have enabled Do Not Track in their browser:

export default {
  fathom: {
    enabled: true,
    siteId:'ABCDEFGH' 'ABCDEFGH',
    honorDNT: true  // Skip tracking for DNT users
  }
}

Custom Canonical URL

Override the default canonical URL detection:

export default {
  fathom: {
    enabled: true,
    siteId:'ABCDEFGH' 'ABCDEFGH',
    canonical:'https://docs.example.com' 'https://docs.example.com'  // Custom canonical base
  }
}

Disabling Analytics

To temporarily disable analytics without removing the configuration:

export default {
  fathom: {
    enabled: false,  // Analytics disabled
    siteId:'ABCDEFGH' 'ABCDEFGH'
  }
}

Or simply omit the fathom configuration entirely - no tracking script will be added.

Markdown Features Configuration

BunPress supports extensive markdown feature configuration through the markdown options.

Features Toggle

All VitePress-compatible markdown features can be enabled/disabled via the features configuration:

export default {
  markdown: {
    features: {
      // Inline formatting (bold, italic, strikethrough, sub/sup, mark)
      inlineFormatting: true,

      // Custom containers (::: info, ::: tip, etc.)
      containers: true,  // Or configure specific types

      // GitHub alerts (> [!NOTE], > [!TIP], etc.)
      githubAlerts: true,  // Or configure specific types

      // Code block enhancements
      codeBlocks: {
        lineHighlighting: true,
        lineNumbers: true,
        focus: true,
        diffs: true,
        errorWarningMarkers: true
      },

      // Code groups with tabs
      codeGroups: true,

      // Code imports from files
      codeImports: true,

      // Inline TOC <!--INLINE_TOC_PLACEHOLDER--> macro
      inlineToc: true,

      // Custom header anchors (## Heading {#custom-id})
      customAnchors: true,

      // Emoji shortcodes (🎉, 🚀, etc.)
      emoji: true,

      // Inline badges (<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;">v2.0</span>)
      badges: true,

      // Markdown file inclusion (<!--@include: ./file.md-->)
      includes: true,

      // External link enhancements
      externalLinks: {
        autoTarget: true,  // Add target="_blank"
        autoRel: true,     // Add rel="noreferrer noopener"
        showIcon: true     // Show external link icon
      },

      // Image lazy loading
      imageLazyLoading: true,

      // Enhanced tables
      tables: {
        alignment: true,       // Column alignment support
        enhancedStyling: true, // Striped rows, hover effects
        responsive: true       // Horizontal scroll wrapper
      }
    }
  }
}

Fine-Grained Container Control

export default {
  markdown: {
    features: {
      containers: {
        info: true,
        tip: true,
        warning: true,
        danger: true,
        details: true,
        raw: false  // Disable raw containers
      }
    }
  }
}

Fine-Grained Alert Control

export default {
  markdown: {
    features: {
      githubAlerts: {
        note: true,
        tip: true,
        important: true,
        warning: true,
        caution: false  // Disable caution alerts
      }
    }
  }
}

Disabling Specific Features

export default {
  markdown: {
    features: {// Disable features you don't need
      // Disable features you don't need
      emoji: false,           // Disable emoji processing
      badges: false,          // Disable badge syntax
      imageLazyLoading: false // Disable lazy loading
    }
  }
}

Table of Contents

Configure TOC generation:

export default {
  markdown: {
    toc: {
      enabled: true,
      minDepth: 2,  // Start from H2
      maxDepth: 4,   // End at H4
      position:'sidebar' 'sidebar',// 'sidebar', 'inline', or 'floating' // 'sidebar', 'inline', or 'floating'
      title:'On This Page' 'On This Page',
      exclude: ['Appendix''Appendix','References' 'References'],
      pattern:'^(Appendix|References)' '^(Appendix|References)',  // Regex pattern for exclusion
      collapsible: true,
      collapsed: false
    }
  }
}

TOC Configuration Properties

Code Highlighting

Configure syntax highlighting:

export default {
  markdown: {
    highlighting: {
      enabled: true,
      theme:'github-dark' 'github-dark',
      lineNumbers: true,
      copyButton: true,
      languages: ['typescript'
        'typescript','javascript' 'javascript','python' 'python','rust' 'rust','go' 'go'
      ]
    }
  }
}

GitHub Alerts

GitHub-style alert boxes are enabled by default. All alert types are supported:

• [!NOTE] - Essential information
• [!TIP] - Helpful advice
• [!IMPORTANT] - Critical information
• [!WARNING] - Urgent attention required
• [!CAUTION] - Potential risks

No configuration required - use them directly in your markdown:

<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>This is automatically styled!</p>
  </div>
</div>

Custom Containers

Custom container syntax is enabled by default:

<div class="custom-block tip">
  <p class="custom-block-title">TIP</p>
  <div class="custom-block-content">
    <p>This is a tip</p>
  </div>
</div>


<div class="custom-block warning">
  <p class="custom-block-title">WARNING</p>
  <div class="custom-block-content">
    <p>This is a warning</p>
  </div>
</div>


<div class="custom-block danger">
  <p class="custom-block-title">DANGER</p>
  <div class="custom-block-content">
    <p>This is dangerous</p>
  </div>
</div>


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


<details class="custom-block details">
  <summary>Click to expand</summary>
  <div class="custom-block-content">
    <p>Hidden content</p>
  </div>
</details>

Code Groups

Code groups are automatically processed when using the syntax:

<div class="code-group" id="code-group-bv4z71vik">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-bv4z71vik', 0)">JavaScript</button><button class="code-group-tab " onclick="switchCodeTab('code-group-bv4z71vik', 1)">TypeScript</button>
  </div>
  <div class="code-group-panels">
    <div class="code-group-panel active" data-panel="0">
  <pre data-lang="js"><code class="language-js"><span class="token comment-line-double-slash-js" style="color: #6e7781; font-style: italic">// code here</span></code></pre>
</div>
<div class="code-group-panel " data-panel="1">
  <pre data-lang="ts"><code class="language-ts"><span class="token comment-line-double-slash-ts" style="color: #6e7781; font-style: italic">// code here</span></code></pre>
</div>
  </div>
</div>

Inline Badges

Badges work out of the box:

<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;">new</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</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;">beta</span>

Emoji Support

Emoji shortcodes are automatically converted:

❤️ 🔥 🚀

Configure custom emoji mappings:

export default {
  markdown: {
    emoji: {
      enabled: true,
      customMappings: {'custom'
        'custom':'🎯' '🎯','logo'
        'logo':'🚀' '🚀'
      }
    }
  }
}

Code Imports

Import code from files with the <<< syntax:

<<< ./examples/code.ts
<<< ./src/api.ts{10-20}
<<< ./src/config.ts{#region-name}

Configure base directories:

export default {
  markdown: {
    codeImports: {
      basePath:'./examples' './examples',
      extensions: ['.ts''.ts','.js' '.js','.py' '.py','.go' '.go']
    }
  }
}

Markdown File Inclusion

Include markdown files with HTML comment syntax:

<!--@include: ./shared/intro.md-->
<!--@include: ./guide.md{1-50}-->
<!--@include: ./docs.md{#section}-->

Configure base paths:

export default {
  markdown: {
    includes: {
      basePath:'./docs' './docs',
      maxDepth: 10,  // Maximum nesting level
      circularCheck: true
    }
  }
}

Frontmatter Configuration

Configure page-specific settings via frontmatter:

---
title: Page Title
description: Page description for SEO
layout: doc  # 'home', 'doc', or 'page'

# TOC Configuration
toc:
  enabled: true
  minDepth: 2
  maxDepth: 4

# Hero Section (for home layout)
hero:
  name: Project Name
  text: Tagline
  tagline: Subheading
  image: /logo.png
  actions:
    - theme: brand
      text: Get Started
      link: /guide/start
    - theme: alt
      text: View on GitHub
      link: https://github.com/user/repo

# Features (for home layout)
features:
  - title: Feature 1
    details: Description of feature 1
  - title: Feature 2
    details: Description of feature 2

# Navigation overrides
sidebar: false  # Disable sidebar for this page
navbar: true    # Show/hide navbar
editLink: true  # Show edit link
lastUpdated: true  # Show last updated date

# SEO
head:
  - - meta
    - name: keywords
      content: keyword1, keyword2
  - - meta
    - property: og:title
      content: Custom OG Title
---

Default CSS

BunPress includes a default stylesheet that provides a clean, responsive layout for your documentation.