Getting Started

Get Pepa running and publish your first doc in under ten minutes.

611 words·4 min read

Pepa is an open-source documentation platform you own completely. Clone it, fill it with your content, and ship it — no vendor lock-in, no monthly bill, no login required to read your own docs.

This guide walks you through setup from zero to a live site with your first custom page.

Before you begin

You'll need three things installed on your machine:

corepack enable
corepack prepare pnpm@latest --activate

Set up Pepa

git clone https://github.com/your-org/pepa my-docs
cd my-docs

pnpm install

cd apps/docs
pnpm dev

const config: PepaConfig = {
  name: "my-docs",          // ← change this to your project name
  sections: [
    { id: "docs",          label: "Docs",          href: "/getting-started", enabled: true },
    { id: "api-reference", label: "API Reference", href: "/api-reference",   enabled: false }, // ← enable when ready
    { id: "cookbook",      label: "Cookbook",      href: "/cookbook/overview", enabled: false },
  ],
  // ...
}

content/docs/introduction.mdx  →  localhost:3000/introduction
content/docs/api/auth.mdx      →  localhost:3000/api/auth

---
title: My First Page
description: A short description shown under the title.
type: tutorial
section: docs
nav: Tutorials
order: 1
---
 
Hello, world! This is my first Pepa page.

How the sidebar works

There is no nav config file. The sidebar is generated entirely from your frontmatter fields:

A page with nav: Reference and order: 2 will appear as the second item in the "Reference" group. That's it — no other config needed.

How the project is organized

pepa/
├── apps/
│   └── docs/
│       ├── content/docs/      ← Your MDX files live here
│       ├── app/               ← Next.js App Router pages and layouts
│       ├── components/        ← Sidebar, TOC, MDX renderer, top tabs
│       ├── lib/               ← nav.ts (builds the sidebar), vars.ts (text variables)
│       ├── scripts/           ← CLI tools: search index, find-replace sweep, llms.txt
│       ├── openapi/           ← Your OpenAPI spec (copied to public/ at build time)
│       └── pepa.config.ts     ← Site name, enabled sections, feature flags
│
└── packages/
    └── ui/
        └── src/               ← Shared components: Callout, Tabs, Steps, Tiles, etc.
            └── snippets/      ← Reusable content blocks (edit once, updates everywhere)

The only folder you'll spend most of your time in is content/docs/. Everything else can stay as-is until you want to customize deeper.

Writing in MDX

MDX is Markdown with superpowers. Everything you already know from Markdown works exactly the same — headings, bold, lists, code blocks, links. MDX just lets you drop in React components when you need richer content.

---
title: How to Authenticate
description: Add bearer token auth to your API requests.
type: how-to
section: docs
nav: How-to Guides
order: 1
---
 
## Get your API key
 
Go to your dashboard and copy your key.
 
<Callout type="warning">
  Never commit your API key to version control.
</Callout>
 
## Make your first request
 
```bash
curl https://api.example.com/v1/widgets \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Build and deploy

When you're ready to publish:

pnpm build

This runs the full pipeline: validates all frontmatter, compiles MDX, generates the search index, and exports a static site into apps/docs/out/. Upload that folder to any static host.

Why the schema is your friend

Every MDX file is validated against a schema before the build runs. If you delete a required field or typo a value, the build fails immediately with a clear error pointing at the exact file — instead of silently shipping a broken page.

Try it: delete the title field at the top of this file and save. Watch the terminal. Then add it back.

Where to go next