BunPress Documentation
⌘ K
GuideAPIExamples

Quick Start Guide

Get up and running with BunPress in minutes. This guide covers the essentials to start building beautiful documentation.

Installation

Prerequisites

  • Bun runtime v1.0 or higher

Install Bun if you haven't already:

curl -fsSL https://bun.sh/install | bash

Install BunPress

bun add bunpress

Or install globally:

bun add -g bunpress

Your First Documentation Site

1. Create Project Structure

mkdir my-docs
cd my-docs

Create a basic directory structure:

my-docs/
├── docs/
│   ├── index.md
│   ├── getting-started.md
│   └── guide/
│       └── features.md
├── bunpress.config.ts
└── package.json

2. Create Your First Page

Create docs/index.md:

---
layout: home
hero:
  name: My Project
  text: Build something amazing
  tagline: Fast, simple, and powerful
  actions:
    - theme: brand
      text: Get Started
      link: /getting-started
    - theme: alt
      text: View on GitHub
      link: https://github.com/yourusername/project
features:
  - title: ⚡️ Lightning Fast
    details: Built on Bun for exceptional performance
  - title: 📝 Markdown Powered
    details: Write content in Markdown with powerful extensions
  - title: 🎨 Customizable
    details: Flexible theming and configuration options
---

3. Add Documentation Content

Create docs/getting-started.md:

# Getting Started

Welcome to the documentation!

<!--INLINE_TOC_PLACEHOLDER-->

## Installation

Install the package:

npm install my-package


## Quick Example

Here's a basic example:

import { myFunction } from 'my-package'

const result = myFunction('hello')

console.log(result)


## Key Features

<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>Check out our advanced features for more capabilities!</p>
  </div>
</div>

- Feature 1
- Feature 2
- Feature 3

4. Configure BunPress

Create bunpress.config.ts:

export default {
  title:'My Documentation' 'My Documentation',
  description:'Documentation for my awesome project' 'Documentation for my awesome project',

  themeConfig: {
    nav: [
      { text:'Home' 'Home', link:'/' '/' },
      { text:'Guide' 'Guide', link:'/getting-started' '/getting-started' },
      { text:'GitHub' 'GitHub', link:'https://github.com/yourusername/project' 'https://github.com/yourusername/project' }
    ],

    sidebar: [
      {
        text:'Getting Started' 'Getting Started',
        items: [
          { text:'Introduction' 'Introduction', link:'/getting-started' '/getting-started' },
          { text:'Features' 'Features', link:'/guide/features' '/guide/features' }
        ]
      }
    ],

    footer: {
      message:'Released under the MIT License.' 'Released under the MIT License.',
      copyright:'Copyright © 2024-present Your Name' 'Copyright © 2024-present Your Name'
    }
  }
}

5. Start Development Server

bunx bunpress dev

Visit http://localhost:3000 to see your documentation site!

6. Build for Production

bunx bunpress build

The built site will be in dist/ directory.

Essential Features

Enhanced Markdown

GitHub Alerts

<div class="github-alert github-alert-note">
  <p class="github-alert-title">
    <svg class="github-alert-icon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>
    Note
  </p>
  <div class="github-alert-content">
    <p>This is important information.</p>
  </div>
</div>

<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>Here's a helpful tip!</p>
  </div>
</div>

<div class="github-alert github-alert-warning">
  <p class="github-alert-title">
    <svg class="github-alert-icon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>
    Warning
  </p>
  <div class="github-alert-content">
    <p>Be careful with this action.</p>
  </div>
</div>

Custom Containers

<div class="custom-block tip">
  <p class="custom-block-title">TIP</p>
  <div class="custom-block-content">
    <p>This is a tip container.</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 container.</p>
  </div>
</div>


<div class="custom-block danger">
  <p class="custom-block-title">DANGER</p>
  <div class="custom-block-content">
    <p>Critical information here.</p>
  </div>
</div>

Inline Badges

New in <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;">v2.0+</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>

Code Groups

<div class="code-group" id="code-group-7njm6uszz">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-7njm6uszz', 0)">JavaScript</button><button class="code-group-tab " onclick="switchCodeTab('code-group-7njm6uszz', 1)">TypeScript</button>
  </div>
  <div class="code-group-panels">
    <div class="code-group-panel active" data-panel="0">
  <pre data-lang="javascript"><code class="language-javascript"><span class="token source-js" style="">console</span><span class="token keyword-operator-js" style="color: #cf222e">.</span><span class="token entity-name-function-js" style="color: #8250df">log</span><span class="token source-js" style="">(</span><span class="token string-quoted-double-js" style="color: #0a3069">&#039;Hello World&#039;</span>'Hello World'<span class="token source-js" style="">)</span></code></pre>
</div>
<div class="code-group-panel " data-panel="1">
  <pre data-lang="typescript"><code class="language-typescript"><span class="token source-ts" style="">console</span><span class="token keyword-operator-ts" style="color: #cf222e">.</span><span class="token entity-name-function-ts" style="color: #8250df">log</span><span class="token source-ts" style="">(</span><span class="token string-quoted-double-ts" style="color: #0a3069">&#039;Hello World&#039;</span>'Hello World' <span class="token keyword-operator-new-ts" style="color: #cf222e">as</span> <span class="token storage-type-ts" style="color: #cf222e">string</span><span class="token source-ts" style="">)</span></code></pre>
</div>
  </div>
</div>

Emoji Support

I ❤️ BunPress! 🚀

Renders as: I ❤️ BunPress! 🚀

Advanced Code Features

Line Highlighting

function example() {

// This line is highlighted

const data = fetchData()

// These lines are highlighted

if (data) {

return processData(data)

}

}

Line Numbers

function calculate(x: number): number {

return x * 2

}

File Names

export function helper() {

// implementation

}

Code Imports

Import code from actual files:

<<< ./examples/demo.ts

<<< ./src/api.ts{10-20}

<<< ./src/config.ts{#setup}

In your source file:

// #region setup
export const config = {
  apiUrl:'https://api.example.com' 'https://api.example.com'
}
// #endregion setup

Markdown File Inclusion

Reuse content across pages:

<!--@include: ./shared/intro.md-->

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

<!--@include: ./components/features.md{#overview}-->

Table of Contents

Add TOC anywhere in your page:

<!--INLINE_TOC_PLACEHOLDER-->

Configure in frontmatter:

---
title: My Page
toc:
  minDepth: 2
  maxDepth: 4
---

Project Structure

Recommended structure for documentation:

my-docs/
├── docs/
│   ├── public/           # Static assets
│   │   ├── images/
│   │   └── favicon.ico
│   ├── .vitepress/       # (optional) theme customization
│   ├── index.md          # Home page
│   ├── getting-started.md
│   └── guide/
│       ├── introduction.md
│       ├── installation.md
│       └── features.md
├── examples/             # Code examples for imports
│   ├── basic.ts
│   └── advanced.ts
├── bunpress.config.ts    # Configuration
└── package.json

Configuration Basics

Essential Config Options

export default {
  // Site metadata
  title:'My Docs' 'My Docs',
  description:'Site description' 'Site description',
  base:'/' '/',  // Base URL path

  // Theme config
  themeConfig: {
    logo:'/logo.png' '/logo.png',

    // Navigation
    nav: [
      { text:'Home' 'Home', link:'/' '/' },
      { text:'Guide' 'Guide', link:'/guide/' '/guide/' },
      {
        text:'Resources' 'Resources',
        items: [
          { text:'API' 'API', link:'/api/' '/api/' },
          { text:'Examples' 'Examples', link:'/examples/' '/examples/' }
        ]
      }
    ],

    // Sidebar
    sidebar: [
      {
        text:'Guide' 'Guide',
        collapsed: false,
        items: [
          { text:'Introduction' 'Introduction', link:'/guide/intro' '/guide/intro' },
          { text:'Getting Started' 'Getting Started', link:'/guide/start' '/guide/start' }
        ]
      }
    ],

    // Social links
    socialLinks: [
      { icon:'github' 'github', link:'https://github.com/yourrepo' 'https://github.com/yourrepo' }
    ],

    // Footer
    footer: {
      message:'Released under MIT License' 'Released under MIT License',
      copyright:'Copyright © 2024' 'Copyright © 2024'
    }
  },

  // Markdown config
  markdown: {
    toc: {
      minDepth: 2,
      maxDepth: 4
    }
  }
}

Development Workflow

Development Server

Start the dev server:

bunx bunpress dev

With custom port:

bunx bunpress dev --port 8080

Building

Build for production:

bunx bunpress build

Preview the build:

bunx bunpress serve

Writing Content

1. Create .md files in docs/ directory

2. Add frontmatter for page metadata

3. Write content using enhanced markdown

4. Preview changes instantly in dev server

5. Build when ready to deploy

Tips & Best Practices

Content Organization

  • Use descriptive filenames: getting-started.md instead of gs.md
  • Group related content: Use subdirectories for logical groupings
  • Consistent naming: Follow a naming convention (kebab-case recommended)

Markdown Writing

  • Use headings hierarchically: Don't skip heading levels
  • Add frontmatter: Include title and description for better SEO
  • Use TOC wisely: Place after introduction paragraph
  • Leverage includes: Reuse common content with markdown includes

Code Examples

  • Import from source: Use code imports for real code examples
  • Add context: Explain what code does before showing it
  • Use line highlighting: Draw attention to important lines
  • Provide alternatives: Use code groups for multi-language examples

Performance

  • Optimize images: Compress images before adding to public/
  • Lazy load: Large images and assets benefit from lazy loading
  • Code splitting: Organize content to enable efficient bundling

Common Patterns

API Documentation Page

---
title: API Reference
description: Complete API documentation
---

# API Reference

<!--INLINE_TOC_PLACEHOLDER-->

## Configuration

Configuration options for the library:

<<< ./src/types.ts{#config}

## Core Methods

### `initialize()`

Initialize the library with configuration.

import { initialize } from 'my-lib'

initialize({

apiKey: 'your-key',

debug: true

})


<div class="github-alert github-alert-warning">
  <p class="github-alert-title">
    <svg class="github-alert-icon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>
    Warning
  </p>
  <div class="github-alert-content">
    <p>Never commit API keys to version control!</p>
  </div>
</div>

### `connect()`

Establish connection to the service.

Available in <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;">v2.0+</span>

<div class="code-group" id="code-group-sik2blta3">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-sik2blta3', 0)">TypeScript</button><button class="code-group-tab " onclick="switchCodeTab('code-group-sik2blta3', 1)">JavaScript</button>
  </div>
  <div class="code-group-panels">
    <div class="code-group-panel active" data-panel="0">
  <pre data-lang="typescript"><code class="language-typescript"><span class="token keyword-control-ts" style="color: #cf222e">await</span> <span class="token entity-name-function-ts" style="color: #8250df">connect</span><span class="token source-ts" style="">(</span><span class="token source-ts" style="">{</span>
  <span class="token source-ts" style="">timeout</span><span class="token keyword-operator-ts" style="color: #cf222e">:</span> <span class="token constant-numeric-ts" style="color: #0550ae">5000</span><span class="token source-ts" style="">,</span>
  <span class="token source-ts" style="">retries</span><span class="token keyword-operator-ts" style="color: #cf222e">:</span> <span class="token constant-numeric-ts" style="color: #0550ae">3</span>
<span class="token source-ts" style="">}</span><span class="token source-ts" style="">)</span></code></pre>
</div>
<div class="code-group-panel " data-panel="1">
  <pre data-lang="javascript"><code class="language-javascript"><span class="token keyword-control-js" style="color: #cf222e">await</span> <span class="token entity-name-function-js" style="color: #8250df">connect</span><span class="token source-js" style="">(</span><span class="token source-js" style="">{</span>
  <span class="token source-js" style="">timeout</span><span class="token keyword-operator-js" style="color: #cf222e">:</span> <span class="token constant-numeric-js" style="color: #0550ae">5000</span><span class="token source-js" style="">,</span>
  <span class="token source-js" style="">retries</span><span class="token keyword-operator-js" style="color: #cf222e">:</span> <span class="token constant-numeric-js" style="color: #0550ae">3</span>
<span class="token source-js" style="">}</span><span class="token source-js" style="">)</span></code></pre>
</div>
  </div>
</div>

Tutorial Page

---
title: Building Your First App
description: Step-by-step tutorial
---

# Building Your First App

Learn how to build your first application with our framework.

<!--INLINE_TOC_PLACEHOLDER-->

## Prerequisites

<div class="github-alert github-alert-note">
  <p class="github-alert-title">
    <svg class="github-alert-icon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>
    Note
  </p>
  <div class="github-alert-content">
    <p>Make sure you have Node.js 18+ and npm installed.</p>
  </div>
</div>

## Step 1: Setup

Create a new project:

npm create my-app@latest

cd my-app

npm install


## Step 2: Configuration

<!--@include: ./shared/config-setup.md-->

## Step 3: First Component

Create your first component:

<<< ./examples/first-component.tsx

<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>Use TypeScript for better type safety!</p>
  </div>
</div>

## Next Steps

<div class="custom-block tip">
  <p class="custom-block-title">What's Next?</p>
  <div class="custom-block-content">
    <p>- Read the <a href="/advanced">advanced guide</a></p>
<p>- Check out <a href="/examples">examples</a></p>
<p>- Join our <a href="https://discord.gg/example">community</a></p>
  </div>
</div>

Next Steps

Now that you're familiar with the basics:

1. Explore features: Check out the features overview

2. Advanced configuration: Read the config guide

3. Markdown extensions: Learn about markdown extensions

4. Best practices: Follow our best practices guide

Getting Help

  • Documentation: Browse the full docs
  • GitHub Issues: Report bugs or request features
  • Community: Join our Discord server
  • Examples: Check out example projects

Happy documenting! 🚀