Examples

Real-world examples of BunPress features in action. Copy and adapt these examples for your own documentation.

Documentation Page Templates

API Reference Page

A typical API documentation page with all features:

---
title: API Reference
description: Complete API documentation for MyLib
layout: doc
toc:
  minDepth: 2
  maxDepth: 3
---

# API Reference

Complete reference for MyLib v2.0 <Badge type="tip" text="stable" />

<!--INLINE_TOC_PLACEHOLDER-->

## Installation

> [!TIP]
> We recommend using the latest version for the best experience.

<div class="code-group" id="code-group-2838be23a430">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-2838be23a430', 0)">npm</button><button class="code-group-tab" onclick="switchCodeTab('code-group-2838be23a430', 1)">yarn</button><button class="code-group-tab" onclick="switchCodeTab('code-group-2838be23a430', 2)">bun</button>
  </div>
  <div class="code-group-panels">
    <div class="code-group-panel active" data-panel="0">
  <pre data-lang="bash"><code class="language-bash"><span class="line"><span class="token source-bash" style="">npm</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">install</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">mylib</span></span>
<span class="line"></span></code></pre>
</div>
<div class="code-group-panel" data-panel="1">
  <pre data-lang="bash"><code class="language-bash"><span class="line"><span class="token source-bash" style="">yarn</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">add</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">mylib</span></span>
<span class="line"></span></code></pre>
</div>
<div class="code-group-panel" data-panel="2">
  <pre data-lang="bash"><code class="language-bash"><span class="line"><span class="token source-bash" style="">bun</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">add</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">mylib</span></span>
<span class="line"></span></code></pre>
</div>
  </div>
</div>

## Configuration

Import and configure the library:

<<< ./examples/config.ts{#basic-config}

### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | `string` | required | Your API key |
| `timeout` | `number` | `5000` | Request timeout in ms |
| `retries` | `number` | `3` | Number of retry attempts |

> [!WARNING]
> Never commit your API keys to version control!

## Core Methods

### `initialize(config)`

Initialize the library with configuration.

**Parameters:**

- `config` (object): Configuration object

**Returns:** `Promise<Client>`

**Example:**

```typescript
import { initialize } from 'mylib'

const client = await initialize({
  apiKey: process.env.API_KEY,
  timeout: 10000
})
```

### `connect(options)` <Badge type="tip" text="v2.0+" />

Establish connection to the service.

**Parameters:**

- `options` (object): Connection options

**Example:**

<div class="code-group" id="code-group-b0418b72aff2">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-b0418b72aff2', 0)">TypeScript</button><button class="code-group-tab" onclick="switchCodeTab('code-group-b0418b72aff2', 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 storage-type-ts" style="color: #cf222e">interface</span><span class="token source-ts" style=""> </span><span class="token source-ts" style="">ConnectOptions</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 keyword-operator-ts" style="color: #cf222e">:</span><span class="token source-ts" style=""> </span><span class="token storage-type-ts" style="color: #cf222e">number</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 keyword-operator-ts" style="color: #cf222e">:</span><span class="token source-ts" style=""> </span><span class="token storage-type-ts" style="color: #cf222e">number</span></span>
<span class="line"><span class="token source-ts" style="">}</span></span>
<span class="line"></span>
<span class="line"><span class="token keyword-control-ts" style="color: #cf222e">await</span><span class="token source-ts" style=""> </span><span class="token source-ts" style="">client</span><span class="token keyword-operator-ts" style="color: #cf222e">.</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 source-js" style="">client</span><span class="token keyword-operator-js" style="color: #cf222e">.</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>

### `disconnect()`

Close the connection gracefully.

> [!IMPORTANT]
> Always call `disconnect()` when you're done to free resources.

```typescript
await client.disconnect()
```

## Advanced Usage

### Error Handling

Handle errors appropriately:

<<< ./examples/error-handling.ts

### Retry Logic

Implement custom retry logic:

<<< ./examples/retry-logic.ts{#retry-implementation}

## Migration Guide

### From v1.x to v2.0

> [!CAUTION]
> Version 2.0 includes breaking changes.

Key changes:

1. **Configuration** <Badge type="danger" text="breaking" />
   - `apiKey` is now required
   - `baseUrl` has been renamed to `endpoint`

2. **Methods** <Badge type="warning" text="deprecated" />
   - `connect()` replaces deprecated `init()`
   - `disconnect()` replaces deprecated `close()`

::: details View full migration guide
<!--@include: ./migration/v1-to-v2.md-->
:::

## See Also

- [Quick Start Guide](/quick-start)
- [Configuration Reference](/config)
- [GitHub Repository](https://github.com/example/mylib)

Tutorial Page

Step-by-step tutorial with progressive disclosure:

---
title: Building Your First App
description: Learn to build an app from scratch
layout: doc
---

# Building Your First App

Learn how to build your first application with our framework. :rocket:

## Prerequisites

> [!NOTE]
> Make sure you have the following installed:
> - Node.js 18+ or Bun 1.0+
> - Git
> - A code editor (VS Code recommended)

## Project Setup

### Step 1: Create Project

Create a new project directory:

```bash
mkdir my-first-app
cd my-first-app
bun init -y
```

### Step 2: Install Dependencies

<div class="code-group" id="code-group-7e2089520062">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-7e2089520062', 0)">Bun</button><button class="code-group-tab" onclick="switchCodeTab('code-group-7e2089520062', 1)">npm</button>
  </div>
  <div class="code-group-panels">
    <div class="code-group-panel active" data-panel="0">
  <pre data-lang="bash"><code class="language-bash"><span class="line"><span class="token source-bash" style="">bun</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">add</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">express</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">@</span><span class="token source-bash" style="">types</span><span class="token source-bash" style="">/</span><span class="token source-bash" style="">express</span></span>
<span class="line"><span class="token source-bash" style="">bun</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">add</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">-</span><span class="token source-bash" style="">d</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">typescript</span></span>
<span class="line"></span></code></pre>
</div>
<div class="code-group-panel" data-panel="1">
  <pre data-lang="bash"><code class="language-bash"><span class="line"><span class="token source-bash" style="">npm</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">install</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">express</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">@</span><span class="token source-bash" style="">types</span><span class="token source-bash" style="">/</span><span class="token source-bash" style="">express</span></span>
<span class="line"><span class="token source-bash" style="">npm</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">install</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">-</span><span class="token source-bash" style="">D</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">typescript</span></span>
<span class="line"></span></code></pre>
</div>
  </div>
</div>

### Step 3: Project Structure

Create the following structure:

```
my-first-app/
├── src/
│   ├── index.ts
│   ├── routes/
│   └── utils/
├── package.json
└── tsconfig.json
```

## Building the Server

### Basic Server Setup

Create `src/index.ts`:

<<< ./examples/tutorial/basic-server.ts

> [!TIP]
> Use TypeScript for better type safety and IDE support!

### Adding Routes

Create `src/routes/api.ts`:

<<< ./examples/tutorial/routes.ts{#api-routes}

### Middleware

Add middleware for common tasks:

<div class="code-group" id="code-group-49cfc4a77e35">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-49cfc4a77e35', 0)">Logging Middleware</button><button class="code-group-tab" onclick="switchCodeTab('code-group-49cfc4a77e35', 1)">Auth Middleware</button><button class="code-group-tab" onclick="switchCodeTab('code-group-49cfc4a77e35', 2)">Error Handler</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-operator-ts" style="color: #cf222e">&lt;&lt;</span><span class="token keyword-operator-ts" style="color: #cf222e">&lt;</span><span class="token source-ts" style=""> </span><span class="token keyword-operator-ts" style="color: #cf222e">.</span><span class="token keyword-operator-ts" style="color: #cf222e">/</span><span class="token source-ts" style="">examples</span><span class="token keyword-operator-ts" style="color: #cf222e">/</span><span class="token source-ts" style="">tutorial</span><span class="token keyword-operator-ts" style="color: #cf222e">/</span><span class="token source-ts" style="">middleware</span><span class="token keyword-operator-ts" style="color: #cf222e">.</span><span class="token source-ts" style="">ts</span><span class="token source-ts" style="">{</span><span class="token source-ts" style="">#</span><span class="token source-ts" style="">logging</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="typescript"><code class="language-typescript"><span class="line"><span class="token keyword-operator-ts" style="color: #cf222e">&lt;&lt;</span><span class="token keyword-operator-ts" style="color: #cf222e">&lt;</span><span class="token source-ts" style=""> </span><span class="token keyword-operator-ts" style="color: #cf222e">.</span><span class="token keyword-operator-ts" style="color: #cf222e">/</span><span class="token source-ts" style="">examples</span><span class="token keyword-operator-ts" style="color: #cf222e">/</span><span class="token source-ts" style="">tutorial</span><span class="token keyword-operator-ts" style="color: #cf222e">/</span><span class="token source-ts" style="">middleware</span><span class="token keyword-operator-ts" style="color: #cf222e">.</span><span class="token source-ts" style="">ts</span><span class="token source-ts" style="">{</span><span class="token source-ts" style="">#</span><span class="token source-ts" style="">auth</span><span class="token source-ts" style="">}</span></span>
<span class="line"></span></code></pre>
</div>
<div class="code-group-panel" data-panel="2">
  <pre data-lang="typescript"><code class="language-typescript"><span class="line"><span class="token keyword-operator-ts" style="color: #cf222e">&lt;&lt;</span><span class="token keyword-operator-ts" style="color: #cf222e">&lt;</span><span class="token source-ts" style=""> </span><span class="token keyword-operator-ts" style="color: #cf222e">.</span><span class="token keyword-operator-ts" style="color: #cf222e">/</span><span class="token source-ts" style="">examples</span><span class="token keyword-operator-ts" style="color: #cf222e">/</span><span class="token source-ts" style="">tutorial</span><span class="token keyword-operator-ts" style="color: #cf222e">/</span><span class="token source-ts" style="">middleware</span><span class="token keyword-operator-ts" style="color: #cf222e">.</span><span class="token source-ts" style="">ts</span><span class="token source-ts" style="">{</span><span class="token source-ts" style="">#</span><span class="token source-ts" style="">error</span><span class="token keyword-operator-ts" style="color: #cf222e">-</span><span class="token source-ts" style="">handler</span><span class="token source-ts" style="">}</span></span>
<span class="line"></span></code></pre>
</div>
  </div>
</div>

## Testing

### Writing Tests

Create tests for your application:

```typescript:line-numbers {8-12}
import { describe, test, expect } from 'bun:test'
import { app } from './index'

describe('API Routes', () => {
  test('GET / returns 200', async () => {
    const response = await app.fetch(new Request('http://localhost/'))
    expect(response.status).toBe(200)

    const data = await response.json()
    expect(data).toHaveProperty('message')
    expect(data.message).toBe('Hello World')
  })
})
```

### Running Tests

```bash
bun test
```

> [!NOTE]
> All tests should pass before deploying!

## Deployment

### Preparing for Production

::: warning Production Checklist

- [ ] Environment variables configured
- [ ] Database migrations run
- [ ] Tests passing
- [ ] Error logging set up
- [ ] Performance monitoring enabled

:::

### Deploy to Cloud

Deploy your application:

```bash

# Build the application

bun run build

# Deploy (example with fly.io)

fly deploy
```

## Next Steps

Congratulations! :tada: You've built your first app!

### What's Next

::: tip Continue Learning

1. Add a database layer
2. Implement authentication
3. Set up CI/CD pipeline
4. Monitor performance

Check out our [Advanced Guide](/advanced) for more.
:::

### Additional Resources

- [Best Practices](/best-practices)
- [Community Discord](https://discord.gg/example)
- [GitHub Examples](https://github.com/example/examples)

Feature Showcase Examples

Code Imports Example

Import code from your actual source files:

## Installation

Import the installation code:

<<< ../package.json{1-10}

## Usage Examples

### Basic Example

<<< ./examples/basic-usage.ts

### With Configuration

Import just the config section:

<<< ./examples/advanced.ts{#configuration}

### Multiple Languages

<div class="code-group" id="code-group-ce1ae6f4ac19">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-ce1ae6f4ac19', 0)">TypeScript</button><button class="code-group-tab" onclick="switchCodeTab('code-group-ce1ae6f4ac19', 1)">JavaScript</button><button class="code-group-tab" onclick="switchCodeTab('code-group-ce1ae6f4ac19', 2)">Python</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-operator-ts" style="color: #cf222e">&lt;&lt;</span><span class="token keyword-operator-ts" style="color: #cf222e">&lt;</span><span class="token source-ts" style=""> </span><span class="token keyword-operator-ts" style="color: #cf222e">.</span><span class="token keyword-operator-ts" style="color: #cf222e">/</span><span class="token source-ts" style="">examples</span><span class="token keyword-operator-ts" style="color: #cf222e">/</span><span class="token source-ts" style="">demo</span><span class="token keyword-operator-ts" style="color: #cf222e">.</span><span class="token source-ts" style="">ts</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-operator-js" style="color: #cf222e">&lt;&lt;</span><span class="token keyword-operator-js" style="color: #cf222e">&lt;</span><span class="token source-js" style=""> </span><span class="token keyword-operator-js" style="color: #cf222e">.</span><span class="token keyword-operator-js" style="color: #cf222e">/</span><span class="token source-js" style="">examples</span><span class="token keyword-operator-js" style="color: #cf222e">/</span><span class="token source-js" style="">demo</span><span class="token keyword-operator-js" style="color: #cf222e">.</span><span class="token source-js" style="">js</span></span>
<span class="line"></span></code></pre>
</div>
<div class="code-group-panel" data-panel="2">
  <pre data-lang="python"><code class="language-python"><span class="line"><span class="token keyword-operator-python" style="color: #cf222e">&lt;</span><span class="token keyword-operator-python" style="color: #cf222e">&lt;</span><span class="token keyword-operator-python" style="color: #cf222e">&lt;</span><span class="token source-python" style=""> </span><span class="token source-python" style="">.</span><span class="token keyword-operator-python" style="color: #cf222e">/</span><span class="token source-python" style="">examples</span><span class="token keyword-operator-python" style="color: #cf222e">/</span><span class="token source-python" style="">demo</span><span class="token source-python" style="">.</span><span class="token source-python" style="">py</span></span>
<span class="line"></span></code></pre>
</div>
  </div>
</div>

Markdown Includes Example

Reuse content across pages:

# Product Documentation

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

## Features

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

## Getting Started

<!--@include: ./guides/quick-start.md{1-50}-->

## API Reference

<!--@include: ./api/endpoints.md{#rest-api}-->

GitHub Alerts Example

Different alert types for different purposes:

## Installation Notes

> [!NOTE]
> This package requires Node.js 18 or higher.

## Performance Tips

> [!TIP]
> Enable caching for better performance in production.

## Security

> [!IMPORTANT]
> Always validate user input before processing.

## Breaking Changes

> [!WARNING]
> Version 3.0 removes support for Node.js 16.

## Data Loss Prevention

> [!CAUTION]
> This operation cannot be undone. Backup your data first!

Badge Usage Example

Version indicators and status badges:

# Features

## Authentication <Badge type="tip" text="stable" />

Production-ready authentication system.

## Real-time Updates <Badge type="info" text="beta" />

Beta feature with active development.

## Legacy API <Badge type="warning" text="deprecated" />

Will be removed in v3.0.

## Breaking Changes <Badge type="danger" text="v2.0+" />

Not compatible with v1.x.

Code Groups Example

Multi-language examples:

## Installation

<div class="code-group" id="code-group-dc2003fe01e1">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-dc2003fe01e1', 0)">npm</button><button class="code-group-tab" onclick="switchCodeTab('code-group-dc2003fe01e1', 1)">yarn</button><button class="code-group-tab" onclick="switchCodeTab('code-group-dc2003fe01e1', 2)">pnpm</button><button class="code-group-tab" onclick="switchCodeTab('code-group-dc2003fe01e1', 3)">bun</button>
  </div>
  <div class="code-group-panels">
    <div class="code-group-panel active" data-panel="0">
  <pre data-lang="bash"><code class="language-bash"><span class="line"><span class="token source-bash" style="">npm</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">install</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">package</span><span class="token source-bash" style="">-</span><span class="token source-bash" style="">name</span></span>
<span class="line"></span></code></pre>
</div>
<div class="code-group-panel" data-panel="1">
  <pre data-lang="bash"><code class="language-bash"><span class="line"><span class="token source-bash" style="">yarn</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">add</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">package</span><span class="token source-bash" style="">-</span><span class="token source-bash" style="">name</span></span>
<span class="line"></span></code></pre>
</div>
<div class="code-group-panel" data-panel="2">
  <pre data-lang="bash"><code class="language-bash"><span class="line"><span class="token source-bash" style="">pnpm</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">add</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">package</span><span class="token source-bash" style="">-</span><span class="token source-bash" style="">name</span></span>
<span class="line"></span></code></pre>
</div>
<div class="code-group-panel" data-panel="3">
  <pre data-lang="bash"><code class="language-bash"><span class="line"><span class="token source-bash" style="">bun</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">add</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">package</span><span class="token source-bash" style="">-</span><span class="token source-bash" style="">name</span></span>
<span class="line"></span></code></pre>
</div>
  </div>
</div>

## Configuration Files

<div class="code-group" id="code-group-9068e56e5175">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-9068e56e5175', 0)">TypeScript</button><button class="code-group-tab" onclick="switchCodeTab('code-group-9068e56e5175', 1)">JavaScript</button><button class="code-group-tab" onclick="switchCodeTab('code-group-9068e56e5175', 2)">JSON</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-other-ts" style="color: #cf222e">import</span><span class="token source-ts" style=""> </span><span class="token storage-type-ts" style="color: #cf222e">type</span><span class="token source-ts" style=""> </span><span class="token source-ts" style="">{</span><span class="token source-ts" style=""> </span><span class="token source-ts" style="">Config</span><span class="token source-ts" style=""> </span><span class="token source-ts" style="">}</span><span class="token source-ts" style=""> </span><span class="token keyword-other-ts" style="color: #cf222e">from</span><span class="token source-ts" style=""> </span><span class="token string-quoted-double-ts" style="color: #0a3069">&#039;package-name&#039;</span></span>
<span class="line"></span>
<span class="line"><span class="token keyword-other-ts" style="color: #cf222e">export</span><span class="token source-ts" style=""> </span><span class="token keyword-control-ts" style="color: #cf222e">default</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="">apiKey</span><span class="token keyword-operator-ts" style="color: #cf222e">:</span><span class="token source-ts" style=""> </span><span class="token source-ts" style="">process</span><span class="token keyword-operator-ts" style="color: #cf222e">.</span><span class="token source-ts" style="">env</span><span class="token keyword-operator-ts" style="color: #cf222e">.</span><span class="token source-ts" style="">API_KEY</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>
<span class="line"><span class="token source-ts" style="">}</span><span class="token source-ts" style=""> </span><span class="token source-ts" style="">satisfies</span><span class="token source-ts" style=""> </span><span class="token source-ts" style="">Config</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 source-js" style="">module</span><span class="token keyword-operator-js" style="color: #cf222e">.</span><span class="token source-js" style="">exports</span><span class="token source-js" style=""> </span><span class="token keyword-operator-js" style="color: #cf222e">=</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="">apiKey</span><span class="token keyword-operator-js" style="color: #cf222e">:</span><span class="token source-js" style=""> </span><span class="token source-js" style="">process</span><span class="token keyword-operator-js" style="color: #cf222e">.</span><span class="token source-js" style="">env</span><span class="token keyword-operator-js" style="color: #cf222e">.</span><span class="token source-js" style="">API_KEY</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>
<span class="line"><span class="token source-js" style="">}</span></span>
<span class="line"></span></code></pre>
</div>
<div class="code-group-panel" data-panel="2">
  <pre data-lang="json"><code class="language-json"><span class="line"><span class="token source-json" style="">{</span></span>
<span class="line"><span class="token source-json" style="">  </span><span class="token string-quoted-double-json" style="color: #0a3069">&quot;apiKey&quot;</span><span class="token source-json" style="">:</span><span class="token source-json" style=""> </span><span class="token string-quoted-double-json" style="color: #0a3069">&quot;your-key&quot;</span><span class="token source-json" style="">,</span></span>
<span class="line"><span class="token source-json" style="">  </span><span class="token string-quoted-double-json" style="color: #0a3069">&quot;timeout&quot;</span><span class="token source-json" style="">:</span><span class="token source-json" style=""> </span><span class="token constant-numeric-json" style="color: #0550ae">5000</span></span>
<span class="line"><span class="token source-json" style="">}</span></span>
<span class="line"></span></code></pre>
</div>
  </div>
</div>

Layout Examples

Home Page Layout

Create an attractive landing page:

---
layout: home
hero:
  name: ProjectName
  text: Modern Development Framework
  tagline: Build faster, ship better, scale easier
  image:
    src: /logo.png
    alt: Project Logo
  actions:

    - theme: brand

      text: Get Started
      link: /guide/getting-started

    - theme: alt

      text: View on GitHub
      link: https://github.com/user/project
features:

  - icon: ⚡

    title: Lightning Fast
    details: Optimized for speed with modern build tools

  - icon: 🔒

    title: Type Safe
    details: Full TypeScript support out of the box

  - icon: 🎨

    title: Customizable
    details: Flexible theming and plugin system

  - icon: 📦

    title: Zero Config
    details: Sensible defaults, works immediately

  - icon: 🚀

    title: Production Ready
    details: Battle-tested in production environments

  - icon: 📚

    title: Well Documented
    details: Comprehensive docs and examples
---

## Quick Start

Get up and running in seconds:

```bash
bun create my-project
cd my-project
bun dev
```

## Sponsors

Special thanks to our sponsors for supporting this project!

Documentation Page Layout

Standard documentation layout:

---
layout: doc
title: Configuration Guide
description: Learn how to configure your application
sidebar: true
editLink: true
lastUpdated: true
toc:
  minDepth: 2
  maxDepth: 3
---

# Configuration Guide

Your content here...

Plain Page Layout

Minimal layout for special pages:

---
layout: page
title: About
navbar: true
sidebar: false
---

# About Us

Custom content without documentation layout...

Common Patterns

Changelog Page

# Changelog

All notable changes to this project are documented here.

## [2.0.0] - 2024-01-15 <Badge type="danger" text="breaking" />

### Added <Badge type="tip" text="new" />

- New feature X with improved performance
- Support for Y configuration
- Enhanced error messages

### Changed <Badge type="warning" text="breaking" />

> [!CAUTION]
> This release contains breaking changes!

- Renamed `oldMethod()` to `newMethod()`
- Changed configuration format
- Updated minimum Node.js version to 18

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

- `legacyFunction()` - Use `modernFunction()` instead
- Old configuration format (will be removed in v3.0)

### Fixed

- Fixed memory leak in connection pool
- Corrected TypeScript definitions
- Resolved race condition in async operations

## [1.5.0] - 2024-01-01

### Added

- Feature A
- Feature B

FAQ Page

# Frequently Asked Questions

Common questions and answers about the project.

<!--INLINE_TOC_PLACEHOLDER-->

## General

### What is this project

> [!NOTE]
> This project is a modern framework for building web applications.

<!--@include: ./shared/project-description.md-->

### Who should use this

::: tip Ideal For

- Full-stack developers
- Frontend engineers
- DevOps teams
- Startup founders

:::

## Installation

### Which package manager should I use

<div class="code-group" id="code-group-5f3664a32d87">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-5f3664a32d87', 0)">Recommended: Bun</button><button class="code-group-tab" onclick="switchCodeTab('code-group-5f3664a32d87', 1)">npm</button><button class="code-group-tab" onclick="switchCodeTab('code-group-5f3664a32d87', 2)">yarn</button>
  </div>
  <div class="code-group-panels">
    <div class="code-group-panel active" data-panel="0">
  <pre data-lang="bash"><code class="language-bash"><span class="line"><span class="token source-bash" style="">bun</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">add</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">package</span><span class="token source-bash" style="">-</span><span class="token source-bash" style="">name</span></span>
<span class="line"></span></code></pre>
</div>
<div class="code-group-panel" data-panel="1">
  <pre data-lang="bash"><code class="language-bash"><span class="line"><span class="token source-bash" style="">npm</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">install</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">package</span><span class="token source-bash" style="">-</span><span class="token source-bash" style="">name</span></span>
<span class="line"></span></code></pre>
</div>
<div class="code-group-panel" data-panel="2">
  <pre data-lang="bash"><code class="language-bash"><span class="line"><span class="token source-bash" style="">yarn</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">add</span><span class="token source-bash" style=""> </span><span class="token source-bash" style="">package</span><span class="token source-bash" style="">-</span><span class="token source-bash" style="">name</span></span>
<span class="line"></span></code></pre>
</div>
  </div>
</div>

> [!TIP]
> We recommend Bun for the best performance!

### Minimum requirements

> [!IMPORTANT]
> Requires Node.js 18+ or Bun 1.0+

## Troubleshooting

### Common Issues

#### Installation fails

> [!WARNING]
> Make sure you have the latest version of your package manager.

Try clearing the cache:

```bash
bun pm cache rm
bun install
```

#### Type errors

::: details Click to expand solution

Check your TypeScript configuration:

<<< ./examples/tsconfig.json

:::

Comparison Page

# BunPress vs Alternatives

How does BunPress compare to other static site generators?

## Quick Comparison

| Feature | BunPress | VitePress | Docusaurus |
|---------|----------|-----------|------------|
| Runtime | Bun | Node.js | Node.js |
| Build Speed | ⚡ Very Fast | Fast | Medium |
| GitHub Alerts | ✅ | ❌ | ❌ |
| Code Imports | ✅ | ✅ | ❌ |
| Markdown Includes | ✅ | ✅ | ❌ |
| React Support | ❌ | ❌ | ✅ |

## Detailed Comparison

### BunPress

::: tip Advantages

- Lightning-fast builds with Bun
- GitHub-flavored alerts
- Extensive markdown features
- Zero configuration needed

:::

::: warning Limitations

- Newer project, smaller ecosystem
- No React component support (yet)

:::

### VitePress

::: info Overview
Mature and stable documentation tool powered by Vite.
:::

Ideal for projects already using the Vite ecosystem.

### Docusaurus

::: info Overview
Feature-rich with React component support.
:::

Best for projects needing custom interactive components.

## Migration Guides

See our migration guides:

- [From VitePress](/migration/from-vitepress)
- [From Docusaurus](/migration/from-docusaurus)

Best Practices

Effective Use of Features

# Best Practices for Feature Usage

## When to Use GitHub Alerts vs Containers

### Use GitHub Alerts for

> [!TIP]
> Quick, inline callouts in documentation

### Use Containers for

::: details Expandable Content
Long-form content that users can expand to read.
:::

## Code Organization

Import real code to keep docs in sync:

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

Don't hardcode examples that might become outdated!

## Content Reuse

Shared content across multiple pages:

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

Reduces duplication and maintenance burden.

Next Steps

• Explore the Features Overview for all capabilities
• Check out the Configuration Guide for customization
• Read Markdown Extensions for syntax details
• Review Best Practices for optimization tips