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 <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;">stable</span>

<!--INLINE_TOC_PLACEHOLDER-->

## Installation

<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>We recommend using the latest version for the best experience.</p>
  </div>
</div>

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

<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 your API keys to version control!</p>
  </div>
</div>

## Core Methods

### `initialize(config)`

Initialize the library with configuration.

**Parameters:**
- `config` (object): Configuration object

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

**Example:**

import { initialize } from 'mylib'

const client = await initialize({

apiKey: process.env.API_KEY,

timeout: 10000

})

### `connect(options)` <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>

Establish connection to the service.

**Parameters:**
- `options` (object): Connection options

**Example:**

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

<span class="token keyword-control-ts" style="color: #cf222e">await</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 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 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 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>

### `disconnect()`

Close the connection gracefully.

<div class="github-alert github-alert-important">
  <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 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>
    Important
  </p>
  <div class="github-alert-content">
    <p>Always call <code>disconnect()</code> when you're done to free resources.</p>
  </div>
</div>

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

<div class="github-alert github-alert-caution">
  <p class="github-alert-title">
    <svg class="github-alert-icon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>
    Caution
  </p>
  <div class="github-alert-content">
    <p>Version 2.0 includes breaking changes.</p>
  </div>
</div>

Key changes:

1. **Configuration** <span class="badge badge-danger" style="display: inline-block; padding: 2px 8px; font-size: 0.85em; font-weight: 600; border-radius: 4px; background: #fee2e2; color: #7f1d1d; border: 1px solid #ef4444; margin: 0 4px; vertical-align: middle;">breaking</span>
   - `apiKey` is now required
   - `baseUrl` has been renamed to `endpoint`

2. **Methods** <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>
   - `connect()` replaces deprecated `init()`
   - `disconnect()` replaces deprecated `close()`

<details class="custom-block details">
  <summary>View full migration guide</summary>
  <div class="custom-block-content">
    <p><!--@include: ./migration/v1-to-v2.md--></p>
  </div>
</details>


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

## 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 the following installed:</p>
<p>- Node.js 18+ or Bun 1.0+</p>
<p>- Git</p>
<p>- A code editor (VS Code recommended)</p>
  </div>
</div>

## Project Setup

### Step 1: Create Project

Create a new project directory:

mkdir my-first-app

cd my-first-app

bun init -y

### Step 2: Install Dependencies

<div class="code-group" id="code-group-42xapp2w2">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-42xapp2w2', 0)">Bun</button><button class="code-group-tab " onclick="switchCodeTab('code-group-42xapp2w2', 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="token source-bash" style="">bun</span> <span class="token source-bash" style="">add</span> <span class="token source-bash" style="">express</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 class="token source-bash" style="">bun</span> <span class="token source-bash" style="">add</span> <span class="token source-bash" style="">-</span><span class="token source-bash" style="">d</span> <span class="token source-bash" style="">typescript</span></code></pre>
</div>
<div class="code-group-panel " data-panel="1">
  <pre data-lang="bash"><code class="language-bash"><span class="token source-bash" style="">npm</span> <span class="token source-bash" style="">install</span> <span class="token source-bash" style="">express</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 class="token source-bash" style="">npm</span> <span class="token source-bash" style="">install</span> <span class="token source-bash" style="">-</span><span class="token source-bash" style="">D</span> <span class="token source-bash" style="">typescript</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

<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 and IDE support!</p>
  </div>
</div>

### 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-4dovzeesx">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-4dovzeesx', 0)">Logging Middleware</button><button class="code-group-tab " onclick="switchCodeTab('code-group-4dovzeesx', 1)">Auth Middleware</button><button class="code-group-tab " onclick="switchCodeTab('code-group-4dovzeesx', 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="token keyword-operator-ts" style="color: #cf222e">&lt;&lt;</span><span class="token keyword-operator-ts" style="color: #cf222e">&lt;</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></code></pre>
</div>
<div class="code-group-panel " data-panel="1">
  <pre data-lang="typescript"><code class="language-typescript"><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 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></code></pre>
</div>
<div class="code-group-panel " data-panel="2">
  <pre data-lang="typescript"><code class="language-typescript"><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 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></code></pre>
</div>
  </div>
</div>

## Testing

### Writing Tests

Create tests for your application:

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

bun test

<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>All tests should pass before deploying!</p>
  </div>
</div>

## Deployment

### Preparing for Production

<div class="custom-block warning">
  <p class="custom-block-title">Production Checklist</p>
  <div class="custom-block-content">
    <p>- [ ] Environment variables configured</p>
<p>- [ ] Database migrations run</p>
<p>- [ ] Tests passing</p>
<p>- [ ] Error logging set up</p>
<p>- [ ] Performance monitoring enabled</p>
  </div>
</div>


### Deploy to Cloud

Deploy your application:

Build the application

bun run build

Deploy (example with fly.io)

fly deploy

## Next Steps

Congratulations! 🎉 You've built your first app!

### What's Next?

<div class="custom-block tip">
  <p class="custom-block-title">Continue Learning</p>
  <div class="custom-block-content">
    <p>1. Add a database layer</p>
<p>2. Implement authentication</p>
<p>3. Set up CI/CD pipeline</p>
<p>4. Monitor performance</p>
<p>Check out our <a href="/advanced">Advanced Guide</a> for more.</p>
  </div>
</div>


### Additional Resources

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

<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 package requires Node.js 18 or higher.</p>
  </div>
</div>

## Performance Tips

<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>Enable caching for better performance in production.</p>
  </div>
</div>

## Security

<div class="github-alert github-alert-important">
  <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 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>
    Important
  </p>
  <div class="github-alert-content">
    <p>Always validate user input before processing.</p>
  </div>
</div>

## Breaking Changes

<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>Version 3.0 removes support for Node.js 16.</p>
  </div>
</div>

## Data Loss Prevention

<div class="github-alert github-alert-caution">
  <p class="github-alert-title">
    <svg class="github-alert-icon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>
    Caution
  </p>
  <div class="github-alert-content">
    <p>This operation cannot be undone. Backup your data first!</p>
  </div>
</div>

Badge Usage Example

Version indicators and status badges:

# Features

## Authentication <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;">stable</span>

Production-ready authentication system.

## Real-time Updates <span class="badge badge-info" style="display: inline-block; padding: 2px 8px; font-size: 0.85em; font-weight: 600; border-radius: 4px; background: #e0f2fe; color: #0c4a6e; border: 1px solid #0ea5e9; margin: 0 4px; vertical-align: middle;">beta</span>

Beta feature with active development.

## Legacy API <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>

Will be removed in v3.0.

## Breaking Changes <span class="badge badge-danger" style="display: inline-block; padding: 2px 8px; font-size: 0.85em; font-weight: 600; border-radius: 4px; background: #fee2e2; color: #7f1d1d; border: 1px solid #ef4444; margin: 0 4px; vertical-align: middle;">v2.0+</span>

Not compatible with v1.x.

Code Groups Example

Multi-language examples:

## Installation

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

## Configuration Files

<div class="code-group" id="code-group-ugu5o5bv3">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-ugu5o5bv3', 0)">TypeScript</button><button class="code-group-tab " onclick="switchCodeTab('code-group-ugu5o5bv3', 1)">JavaScript</button><button class="code-group-tab " onclick="switchCodeTab('code-group-ugu5o5bv3', 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="token keyword-other-ts" style="color: #cf222e">import</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="">Config</span> <span class="token source-ts" style="">}</span> <span class="token keyword-other-ts" style="color: #cf222e">from</span><span class="token string-quoted-double-ts" style="color: #0a3069">&#039;package-name&#039;</span> 'package-name'

<span class="token keyword-other-ts" style="color: #cf222e">export</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="">apiKey</span><span class="token keyword-operator-ts" style="color: #cf222e">:</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 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="">satisfies</span> <span class="token source-ts" style="">Config</span></code></pre>
</div>
<div class="code-group-panel " data-panel="1">
  <pre data-lang="javascript"><code class="language-javascript"><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 keyword-operator-js" style="color: #cf222e">=</span> <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="">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 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></code></pre>
</div>
<div class="code-group-panel " data-panel="2">
  <pre data-lang="json"><code class="language-json"><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 string-quoted-double-json" style="color: #0a3069">&quot;your-key&quot;</span><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 constant-numeric-json" style="color: #0550ae">5000</span>
<span class="token source-json" style="">}</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:

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 <span class="badge badge-danger" style="display: inline-block; padding: 2px 8px; font-size: 0.85em; font-weight: 600; border-radius: 4px; background: #fee2e2; color: #7f1d1d; border: 1px solid #ef4444; margin: 0 4px; vertical-align: middle;">breaking</span>

### Added <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;">new</span>

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

### Changed <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;">breaking</span>

<div class="github-alert github-alert-caution">
  <p class="github-alert-title">
    <svg class="github-alert-icon" viewBox="0 0 16 16" width="16" height="16" aria-hidden="true"><path d="M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>
    Caution
  </p>
  <div class="github-alert-content">
    <p>This release contains breaking changes!</p>
  </div>
</div>

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

### Deprecated <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>

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

<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 project is a modern framework for building web applications.</p>
  </div>
</div>

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

### Who should use this?

<div class="custom-block tip">
  <p class="custom-block-title">Ideal For</p>
  <div class="custom-block-content">
    <p>- Full-stack developers</p>
<p>- Frontend engineers</p>
<p>- DevOps teams</p>
<p>- Startup founders</p>
  </div>
</div>


## Installation

### Which package manager should I use?

<div class="code-group" id="code-group-z3hzr7czx">
  <div class="code-group-tabs">
    <button class="code-group-tab active" onclick="switchCodeTab('code-group-z3hzr7czx', 0)">Recommended: Bun</button><button class="code-group-tab " onclick="switchCodeTab('code-group-z3hzr7czx', 1)">npm</button><button class="code-group-tab " onclick="switchCodeTab('code-group-z3hzr7czx', 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="token source-bash" style="">bun</span> <span class="token source-bash" style="">add</span> <span class="token source-bash" style="">package</span><span class="token source-bash" style="">-</span><span class="token source-bash" style="">name</span></code></pre>
</div>
<div class="code-group-panel " data-panel="1">
  <pre data-lang="bash"><code class="language-bash"><span class="token source-bash" style="">npm</span> <span class="token source-bash" style="">install</span> <span class="token source-bash" style="">package</span><span class="token source-bash" style="">-</span><span class="token source-bash" style="">name</span></code></pre>
</div>
<div class="code-group-panel " data-panel="2">
  <pre data-lang="bash"><code class="language-bash"><span class="token source-bash" style="">yarn</span> <span class="token source-bash" style="">add</span> <span class="token source-bash" style="">package</span><span class="token source-bash" style="">-</span><span class="token source-bash" style="">name</span></code></pre>
</div>
  </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>We recommend Bun for the best performance!</p>
  </div>
</div>

### Minimum requirements?

<div class="github-alert github-alert-important">
  <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 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>
    Important
  </p>
  <div class="github-alert-content">
    <p>Requires Node.js 18+ or Bun 1.0+</p>
  </div>
</div>

## Troubleshooting

### Common Issues

#### Installation fails

<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>Make sure you have the latest version of your package manager.</p>
  </div>
</div>

Try clearing the cache:

bun pm cache rm

bun install

#### Type errors

<details class="custom-block details">
  <summary>Click to expand solution</summary>
  <div class="custom-block-content">
    <p>Check your TypeScript configuration:</p>
<p><<< ./examples/tsconfig.json</p>
  </div>
</details>

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

<div class="custom-block tip">
  <p class="custom-block-title">Advantages</p>
  <div class="custom-block-content">
    <p>- Lightning-fast builds with Bun</p>
<p>- GitHub-flavored alerts</p>
<p>- Extensive markdown features</p>
<p>- Zero configuration needed</p>
  </div>
</div>


<div class="custom-block warning">
  <p class="custom-block-title">Limitations</p>
  <div class="custom-block-content">
    <p>- Newer project, smaller ecosystem</p>
<p>- No React component support (yet)</p>
  </div>
</div>


### VitePress

<div class="custom-block info">
  <p class="custom-block-title">Overview</p>
  <div class="custom-block-content">
    <p>Mature and stable documentation tool powered by Vite.</p>
  </div>
</div>


Ideal for projects already using the Vite ecosystem.

### Docusaurus

<div class="custom-block info">
  <p class="custom-block-title">Overview</p>
  <div class="custom-block-content">
    <p>Feature-rich with React component support.</p>
  </div>
</div>


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:

<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>Quick, inline callouts in documentation</p>
  </div>
</div>

### Use Containers for:

<details class="custom-block details">
  <summary>Expandable Content</summary>
  <div class="custom-block-content">
    <p>Long-form content that users can expand to read.</p>
  </div>
</details>


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