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:

```bash
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

Tip

Check out our advanced features for more capabilities!

Feature 1
Feature 2
Feature 3


### 4. Configure BunPress

Create `bunpress.config.ts`:

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

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

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

    footer: {
      message: 'Released under the MIT License.',
      copyright: '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-6f5urkojj">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-6f5urkojj', 0)">JavaScript</button><button class="code-group-tab " onclick="switchCodeTab('code-group-6f5urkojj', 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="line"><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><span class="token source-js" style="">)</span></span>
<span class="line"></span></code></pre>
</div>
<div class="code-group-panel " data-panel="1">
  <pre data-lang="typescript"><code class="language-typescript"><span class="line"><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> <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></span>
<span class="line"></span></code></pre>
</div>
  </div>
</div>

Emoji Support

I ❤️ BunPress! 🚀

Renders as: I ❤️ BunPress! 🚀

Advanced Code Features

Line Highlighting

```typescript {2,4-6}
function example() {
  // This line is highlighted
  const data = fetchData()
  // These lines are highlighted
  if (data) {
    return processData(data)
  }
}
```

Line Numbers

```typescript:line-numbers
function calculate(x: number): number {
  return x * 2
}
```

File Names

```typescript [src/utils.ts]
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'
}
// #endregion setup

Markdown File Inclusion

Reuse content across pages:

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

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

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

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',
  description: 'Site description',
  base: '/',  // Base URL path

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

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

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

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

    // Footer
    footer: {
      message: 'Released under MIT License',
      copyright: '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

Create .md files in docs/ directory
Add frontmatter for page metadata
Write content using enhanced markdown
Preview changes instantly in dev server
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.

```typescript
import { initialize } from 'my-lib'

initialize({
  apiKey: 'your-key',
  debug: true
})

Warning

Never commit API keys to version control!

`connect()`

Establish connection to the service.

Available in v2.0+

await connect({
  timeout: 5000,
  retries: 3
})

await connect({
  timeout: 5000,
  retries: 3
})


### Tutorial Page

```markdown
---
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:

```bash
npm create my-app@latest
cd my-app
npm install

Step 2: Configuration

Step 3: First Component

Create your first component:

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

Tip

Use TypeScript for better type safety!

Next Steps

What's Next?

- Read the advanced guide

- Check out examples

- Join our community


## Next Steps

Now that you're familiar with the basics:

1. **Explore features**: Check out the [features overview](/features)
2. **Advanced configuration**: Read the [config guide](/config)
3. **Markdown extensions**: Learn about [markdown extensions](/markdown-extensions)
4. **Best practices**: Follow our [best practices guide](/best-practices)

## 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! 🚀