Quick Start Guide

On this page 41

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:

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

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

> [!NOTE]
> This is important information.

> [!TIP]
> Here's a helpful tip!

> [!WARNING]
> Be careful with this action.

Custom Containers

::: tip
This is a tip container.
:::

::: warning
This is a warning container.
:::

::: danger
Critical information here.
:::

Inline Badges

New in <Badge type="tip" text="v2.0+" />

<Badge type="warning" text="deprecated" />

Code Groups

<div class="code-group" id="code-group-7a8370782d68">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-7a8370782d68', 0)">JavaScript</button><button class="code-group-tab" onclick="switchCodeTab('code-group-7a8370782d68', 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 source-ts" style=""> </span><span class="token keyword-operator-new-ts" style="color: #cf222e">as</span><span class="token source-ts" style=""> </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 :heart: BunPress! :rocket:

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 <Badge type="tip" text="v2.0+" />

<div class="code-group" id="code-group-9578a2ed46eb">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-9578a2ed46eb', 0)">TypeScript</button><button class="code-group-tab" onclick="switchCodeTab('code-group-9578a2ed46eb', 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="line"><span class="token keyword-control-ts" style="color: #cf222e">await</span><span class="token source-ts" style=""> </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>
<span class="line"><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 source-ts" style=""> </span><span class="token constant-numeric-ts" style="color: #0550ae">5000</span><span class="token source-ts" style="">,</span></span>
<span class="line"><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 source-ts" style=""> </span><span class="token constant-numeric-ts" style="color: #0550ae">3</span></span>
<span class="line"><span class="token source-ts" style="">}</span><span class="token source-ts" style="">)</span></span>
<span class="line"></span></code></pre>
</div>
<div class="code-group-panel" data-panel="1">
  <pre data-lang="javascript"><code class="language-javascript"><span class="line"><span class="token keyword-control-js" style="color: #cf222e">await</span><span class="token source-js" style=""> </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>
<span class="line"><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 source-js" style=""> </span><span class="token constant-numeric-js" style="color: #0550ae">5000</span><span class="token source-js" style="">,</span></span>
<span class="line"><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 source-js" style=""> </span><span class="token constant-numeric-js" style="color: #0550ae">3</span></span>
<span class="line"><span class="token source-js" style="">}</span><span class="token source-js" style="">)</span></span>
<span class="line"></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

> [!NOTE]
> Make sure you have Node.js 18+ and npm installed.

## Step 1: Setup

Create a new project:

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

> [!TIP]
> Use TypeScript for better type safety!

## Next Steps

::: tip What's Next?

- Read the [advanced guide](/advanced)
- Check out [examples](/examples)
- Join our [community](https://discord.gg/example)

:::

Next Steps

Now that you're familiar with the basics:

Explore features: Check out the features overview
Advanced configuration: Read the config guide
Markdown extensions: Learn about markdown extensions
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! 🚀