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',
    meta: {
      description: 'My project documentation',
      author: 'Your Name',
    },
    scripts: [
      '/js/highlight.js',
    ],
  },
}

Available Options

General Options

Markdown Plugin Options

Navigation Configuration

Configure the navigation bar:

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

NavItem Properties

Mega Menus

A dropdown upgrades itself to a multi-column mega panel as soon as its content needs the room: when any child carries a description, when children are nested one level deeper into groups, or when mega: true is set. A flat list of bare links keeps rendering as the compact flyout, so existing configs are unchanged.

export default {
  themeConfig: {
    nav: [
      {
        text: 'Features',
        activeMatch: '^/features/',
        columns: 2,
        footer: { text: 'See everything', link: '/features', note: 'The full list.' },
        items: [
          {
            text: 'Language',
            items: [
              { text: 'Types', link: '/features/types', description: 'Inference and unions.' },
              { text: 'Macros', link: '/features/macros', description: 'Hygienic, over the AST.' },
            ],
          },
          {
            text: 'Toolchain',
            items: [
              { text: 'CLI', link: '/features/cli', description: 'One binary for everything.' },
            ],
          },
        ],
      },
    ],
  },
}

Below 960px the bar hides its links, and the same tree renders as a stacked disclosure panel behind a menu button. That panel ships on the home and page layouts, which have no sidebar to fall back on; the doc layout keeps using its sidebar hamburger.

Sidebar Configuration

Configure the sidebar navigation:

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

SidebarItem Properties

Search Configuration

Configure search functionality:

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

SearchConfig Properties

Theme Configuration

Customize the appearance of your documentation:

export default {
  markdown: {
    themeConfig: {
      colors: {
        primary: '#3b82f6',
        secondary: '#64748b',
        accent: '#f59e0b'
      },
      fonts: {
        heading: 'Inter, sans-serif',
        body: 'Roboto, sans-serif',
        mono: 'JetBrains Mono, monospace'
      },
      darkMode: true,
      cssVars: {
        'border-radius': '8px',
        'shadow': '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',
  generator: 'BunPress',
  viewport: 'width=device-width, initial-scale=1.0',
}

Sitemap Configuration

Configure sitemap and SEO optimization:

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

Robots.txt Configuration

Configure robots.txt for search engine crawling:

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

    // Custom Fathom script URL (optional)
    // Default: 'https://cdn.usefathom.com/script.js'
    scriptUrl: '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',

    // 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',
    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',
    honorDNT: true  // Skip tracking for DNT users
  }
}

Custom Canonical URL

Override the default canonical URL detection:

export default {
  fathom: {
    enabled: true,
    siteId: 'ABCDEFGH',
    canonical: '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'
  }
}

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 (:tada:, :rocket:, etc.)
      emoji: true,

      // Inline badges (<Badge type="info" text="v2.0" />)
      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
      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', 'inline', or 'floating'
      title: 'On This Page',
      exclude: ['Appendix', 'References'],
      pattern: '^(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',
      lineNumbers: true,
      copyButton: true,
      languages: [
        'typescript', 'javascript', 'python', 'rust', '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:

> [!TIP]
> This is automatically styled!

Custom Containers

Custom container syntax is enabled by default:

::: tip
This is a tip
:::

::: warning
This is a warning
:::

::: danger
This is dangerous
:::

::: info
This is informational
:::

::: details Click to expand
Hidden content
:::

Code Groups

Code groups are automatically processed when using the syntax:

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

Inline Badges

Badges work out of the box:

<Badge type="tip" text="new" />
<Badge type="warning" text="deprecated" />
<Badge type="danger" text="breaking" />
<Badge type="info" text="beta" />

Emoji Support

Emoji shortcodes are automatically converted:

:heart: :fire: :rocket:

Configure custom emoji mappings:

export default {
  markdown: {
    emoji: {
      enabled: true,
      customMappings: {
        'custom': '🎯',
        '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',
      extensions: ['.ts', '.js', '.py', '.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',
      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

  # Small link above the headline: a release note, a launch post
  announcement:
    tag: v2
    text: Read the release notes
    link: /blog/v2

  # Code visual, highlighted by the same highlighter as a markdown fence.
  # Takes the place of `image`. Give a list for a tabbed panel.
  code:
    - file: server.ts
      lang: ts
      content: |
        export default { fetch: () => new Response('hi') }

  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
    link: /features/one          # turns the card into a link
    linkText: Read the guide     # label for the link affordance
    span: 2                      # columns this cell claims (1-3), for a bento

  - title: Feature 2

    details: Description of feature 2

# Navigation overrides
sidebar: false  # Disable sidebar for this page
navbar: true    # Show/hide navbar
editLink: false     # Hide the edit link on this page
lastUpdated: true   # Show the last modified date (or give an ISO 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.