Pepr Documentation

Official documentation site for Pepr - A Kubernetes controller framework built in TypeScript.

Live Site: https://docs.pepr.dev

Overview

This repository contains the build system and site structure for the Pepr documentation site. Documentation content is extracted from the Pepr core repository and example content from the Pepr Excellent Examples repository, then built into a versioned site using Starlight.

Quick Start

Prerequisites

• Node.js (v18 or later)
• npm
• Access to the Pepr core repository

Setup

1. Clone this repository:

    git clone https://github.com/defenseunicorns/pepr-docs.git
    cd pepr-docs
    npm install

2. Clone the Pepr core repository (adjacent to pepr-docs):

cd ..
git clone https://github.com/defenseunicorns/pepr.git

3. Clone the Pepr Excellent Examples repository (adjacent to pepr-docs):

cd ..
git clone https://github.com/defenseunicorns/pepr-excellent-examples.git
cd pepr-docs

4. Create a .env file to configure the repository paths:

# Create .env file with paths to Pepr core and examples repos
# If repositories are siblings:
cat > .env << EOF
CORE=../pepr
EXAMPLES=../pepr-excellent-examples
EOF

# Or if repositories are in different locations:
cat > .env << EOF
CORE=/path/to/pepr
EXAMPLES=/path/to/pepr-excellent-examples
EOF

Build and Run Locally

# Build the site (generates content from core repo and builds site)
npm run build

# Start development server
npm run dev

The site will be available at http://localhost:4321

Preview Production Build

To preview the built site locally (tests redirects and production behavior):

npm run build
npm run preview

Project Structure

pepr-docs/
├── scripts/                 # Build system source code
│   ├── index.mjs            # Main build orchestrator
│   ├── redirects-generator.mjs
│   └── tests/               # Test suite
├── src/                     # Site source
│   ├── content/docs/        # Documentation content (generated, gitignored)
│   ├── components/          # Astro components
│   ├── pages/               # Custom pages
│   └── styles/              # Stylesheets
├── public/                  # Static assets
├── site-docs/               # Documentation site documentation
│   ├── ARCHITECTURE.md      # Build system architecture
│   ├── CONTRIBUTING.md      # Contribution guide
│   └── REDIRECTS.md         # Redirect system guide
├── astro.config.mjs         # Astro/Starlight configuration
└── package.json

Contributing

Content Changes:

• Core documentation must be made in the Pepr core repository
• Example content must be made in the Pepr Excellent Examples repository

Site structure and UI changes should be made in this repository.

See site-docs/CONTRIBUTING.md for full guidelines.

Documentation

• ARCHITECTURE.md - Build system architecture and workflow
• CONTRIBUTING.md - Contribution guidelines and testing
• REDIRECTS.md - Redirect system documentation

Support

• Issues: GitHub Issues
• Pepr Core: GitHub
• Community: Defense Unicorns Community

License

See the main Pepr repository for license information.