Configuration Deep-Dive

BunPress supports comprehensive configuration for customizing every aspect of your documentation site.

Configuration File

Create a bunpress.config.ts in your project root:

import type { BunPressOptions } from 'bunpress'

const config: BunPressOptions = {
  // Basic settings
  verbose: false,
  docsDir: './docs',
  outDir: './dist',

  // Navigation
  nav: [...],

  // Markdown settings
  markdown: {
    title: 'My Documentation',
    sidebar: {...},
    toc: {...},
    features: {...},
  },

  // Site features
  search: {...},
  sitemap: {...},
  robots: {...},
}

export default config

Directory Configuration

export default {
  // Source directory
  docsDir: './docs',

  // Output directory
  outDir: './dist',

  // URL prefix when the docs are mounted under a sub-path
  basePath: '/docs',

  // Reusable .stx components referenced as PascalCase tags in markdown
  componentsDir: './docs/.components',

  // Global JSON data exposed to every page as `data`
  dataDir: './docs/.data',
}

Static assets are served from `<docsDir>/public` and copied to the output
directory on build.

Navigation

Top Navigation

export default {
  nav: [
    { text: 'Home', link: '/' },
    { text: 'Guide', link: '/guide/' },
    {
      text: 'Dropdown',
      items: [
        { text: 'Item 1', link: '/item1' },
        { text: 'Item 2', link: '/item2' },
      ],
    },
    { text: 'GitHub', link: 'https://github.com/...' },
  ],
}

Sidebar

export default {
  markdown: {
    sidebar: {
      '/guide/': [
        {
          text: 'Getting Started',
          items: [
            { text: 'Introduction', link: '/guide/' },
            { text: 'Installation', link: '/guide/installation' },
          ],
        },
        {
          text: 'Advanced',
          collapsed: true,
          items: [
            { text: 'Configuration', link: '/guide/config' },
          ],
        },
      ],
      '/api/': [
        { text: 'API Reference', link: '/api/' },
      ],
    },
  },
}

Markdown Configuration

Title and Meta

export default {
  markdown: {
    title: 'My Documentation',
    meta: {
      description: 'Documentation for my project',
      author: 'Your Name',
      keywords: 'docs, documentation, guide',
    },
  },
}

Table of Contents

export default {
  markdown: {
    toc: {
      enabled: true,
      position: 'sidebar', // 'sidebar' | 'inline' | 'floating'
      title: 'On this page',
      minDepth: 2,
      maxDepth: 4,
      smoothScroll: true,
      activeHighlight: true,
    },
  },
}

Syntax Highlighting

export default {
  markdown: {
    syntaxHighlightTheme: 'github-dark',
    // or dual themes
    syntaxHighlightTheme: {
      light: 'github-light',
      dark: 'github-dark',
    },
  },
}

Features

export default {
  markdown: {
    features: {
      containers: true,
      githubAlerts: true,
      codeBlocks: {
        lineNumbers: true,
        lineHighlighting: true,
        focus: true,
        diffs: true,
        errorWarningMarkers: true,
      },
      codeGroups: true,
      emoji: true,
      badges: true,
    },
  },
}

SEO Configuration

Sitemap

export default {
  sitemap: {
    enabled: true,
    baseUrl: 'https://your-docs.com',
    changefreq: 'weekly',
    priority: 0.8,
    priorityMap: {
      '/': 1.0,
      '/guide/*': 0.9,
      '/api/*': 0.8,
    },
  },
}

Robots.txt

export default {
  robots: {
    enabled: true,
    rules: [
      {
        userAgent: '*',
        allow: ['/'],
        disallow: ['/draft/', '/private/'],
      },
    ],
  },
}

Analytics

Fathom Analytics

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

Custom Analytics

export default {
  head: [
    [
      'script',
      {},
      `
        // Your analytics code
      `,
    ],
  ],
}

Search Configuration

export default {
  search: {
    enabled: true,
    provider: 'local',
    options: {
      maxResults: 10,
      minQueryLength: 2,
    },
  },
}

Theme Configuration

export default {
  themeConfig: {
    logo: '/logo.svg',

    colors: {
      primary: '#3b82f6',
      accent: '#8b5cf6',
    },

    fonts: {
      heading: 'Inter, sans-serif',
      body: 'Inter, sans-serif',
      mono: 'Fira Code, monospace',
    },

    socialLinks: [
      { icon: 'github', link: 'https://github.com/org/repo' },
    ],

    footer: {
      message: 'Released under the MIT License.',
      copyright: 'Copyright © 2026',
    },

    // "Edit this page" link. `:path` becomes the page's path under docsDir.
    editLink: {
      pattern: 'https://github.com/org/repo/edit/main/docs/:path',
      text: 'Edit this page',
    },

    // Last modified date, taken from the file's most recent git commit and
    // falling back to its filesystem timestamp.
    lastUpdated: true,
    // ...or configure it:
    // lastUpdated: { text: 'Updated', formatOptions: { dateStyle: 'long' } },

    // Escape hatches, applied after the theme so they win.
    cssVars: { 'bp-sidebar-width': '300px' },
    css: '.bp-doc h2 { letter-spacing: 0.02em; }',
  },
}

Both editLink and lastUpdated can be overridden per page in frontmatter — see Frontmatter.

Build Options

Build behaviour is controlled by CLI flags rather than config:

bunpress build --minify --sourcemap
bunpress build --no-search-index   # skip the search index
bunpress clean                     # remove build artifacts

To serve the docs under a URL prefix, set basePath (see Directory Configuration).

Development Options

The dev server is configured by CLI flags:

bunpress dev --port 4000 --dir ./docs --open

Environment Variables

export default {
  // Use environment variables
  sitemap: {
    baseUrl: process.env.SITE*URL || 'https://localhost:3000',
  },

  fathom: {
    enabled: process.env.NODE*ENV === 'production',
  },
}

Extending Configuration

Multiple Config Files

// bunpress.config.ts
import baseConfig from './config/base'
import prodConfig from './config/prod'

export default {
  ...baseConfig,
  ...(process.env.NODE_ENV === 'production' ? prodConfig : {}),
}

Config Validation

import { defineConfig } from 'bunpress'

export default defineConfig({
  // Type-safe configuration
})

Related

• Theming - Theme customization
• Performance - Build optimization
• CI/CD Integration - Deployment