README

Paper-Pi

Documentation as easy as π!

A Laravel package for converting markdown documentation files with YAML front matter into beautiful HTML documentation pages with multi-locale support. Fresh-baked by Bake More Pies.

Features

Markdown to HTML Conversion - Write docs in markdown, render as beautiful HTML
Syntax Highlighting - Automatic code syntax highlighting using laravelsu/highlight
Multi-Locale Support - Built-in support for multiple languages
YAML Front Matter - Add metadata (title, description, keywords) to your markdown files
GitHub Edit Links - Automatic "Edit on GitHub" links for collaborative documentation
Flexible Routing - Clean, SEO-friendly URLs with locale support
Customizable Views - Publish and customize all views to match your brand
Configurable - Extensive configuration options

Installation

Step 1: Install via Composer

composer require bakemorepies/paper-pi

The package will be auto-discovered by Laravel.

Step 2: Publish Configuration

Publish the configuration file:

php artisan vendor:publish --tag=paper-pi-config

This creates config/paper-pi.php where you can customize the package behavior.

Step 3: Configure Filesystem Disk

Add a docs disk to your config/filesystems.php:

'disks' => [
    // ... other disks
    
    'docs' => [
        'driver' => 'local',
        'root' => base_path('docs'),
    ],
],

Step 4: Create Documentation Directory

Create your documentation directory structure:

mkdir -p docs/en/docs

Step 5: Publish Routes (Optional)

You can either:

Option A: Auto-load routes (add to .env):

PAPER_PI_AUTO_LOAD_ROUTES=true

Option B: Publish and customize routes:

php artisan vendor:publish --tag=paper-pi-routes

Then include in your routes/web.php:

require __DIR__.'/paper-pi.php';

Step 6: Publish Views (Optional)

If you want to customize the documentation layout:

php artisan vendor:publish --tag=paper-pi-views

Views will be published to resources/views/vendor/paper-pi/.

Usage

Creating Documentation Files

Create markdown files in your docs directory with YAML front matter:

docs/en/docs/index.md:

---
title: Getting Started
description: Learn how to get started with our application
keywords: laravel, documentation, getting started
---

## Welcome to the Documentation

This is the introduction to our documentation.

### Installation

To install, run:

\```bash
composer require vendor/package
\```

### Next Steps

- [Configuration](/en/docs/configuration)
- [Basic Usage](/en/docs/usage)

Directory Structure

Organize your docs with locales and sections:

docs/
├── en/
│   ├── docs/
│   │   ├── index.md
│   │   ├── installation.md
│   │   ├── configuration.md
│   │   └── advanced/
│   │       ├── caching.md
│   │       └── queues.md
│   └── api/
│       └── index.md
└── es/
    └── docs/
        └── index.md

Accessing Documentation

With default configuration, documentation is available at:

http://yourapp.test/en/docs - English documentation index
http://yourapp.test/en/docs/installation - Installation page
http://yourapp.test/en/docs/advanced/caching - Nested pages

Programmatic Usage

You can also use the PaperPi class directly in your code:

use BakeMorePies\PaperPi\PaperPi;

// Create a PaperPi instance
$docs = new PaperPi('en', 'docs/installation');

// Check if document exists
if ($docs->exists()) {
    // Get parsed content and metadata
    $data = $docs->get();
    // Returns: ['title' => '...', 'content' => '...', 'edit' => '...', etc.]
    
    // Or render a view directly
    return $docs->view('paper-pi::docs');
}

// Get all docs for a locale and section
$allDocs = PaperPi::all('en', 'docs');

// Generate documentation URLs
$url = PaperPi::url('en', 'docs/installation');

Configuration

Basic Configuration

Edit config/paper-pi.php to customize the package:

return [
    // Filesystem disk (defined in config/filesystems.php)
    'disk' => 'docs',
    
    // Supported locales
    'locales' => ['en', 'es', 'fr'],
    
    // Default locale
    'default_locale' => 'en',
    
    // Auto-load routes from package
    'auto_load_routes' => false,
    
    // Route prefix (e.g., /en/docs)
    'route_prefix' => 'docs',
    
    // Route middleware
    'route_middleware' => ['web'],
    
    // Edit link configuration
    'edit_link' => [
        'repository' => 'https://github.com/username/repo',
        'branch' => 'main',
        'path' => 'docs',
    ],
];

Environment Variables

You can override config values using .env:

# Filesystem
PAPER_PI_DISK=docs

# Locales
PAPER_PI_DEFAULT_LOCALE=en

# Routes
PAPER_PI_AUTO_LOAD_ROUTES=true
PAPER_PI_ROUTE_PREFIX=docs
PAPER_PI_ROUTE_STRUCTURE=prefix-first

# Middleware
# Note: Use comma-separated values for multiple middleware
# Example: web,auth or web,platform

# GitHub Edit Links
PAPER_PI_EDIT_REPOSITORY=https://github.com/username/repo
PAPER_PI_EDIT_BRANCH=main
PAPER_PI_EDIT_PATH=docs

# Orchid Platform Integration (optional - only if using Orchid)
PAPER_PI_ORCHID_AUTO_LOAD_ROUTES=true

Common Configurations:

For Admin Panels (Laravel Wind, Orchid):

PAPER_PI_ORCHID_AUTO_LOAD_ROUTES=true
PAPER_PI_ROUTE_PREFIX=admin/docs
PAPER_PI_ROUTE_STRUCTURE=prefix-first
PAPER_PI_ROUTE_MIDDLEWARE=web,platform

For Public Documentation:

PAPER_PI_AUTO_LOAD_ROUTES=true
PAPER_PI_ROUTE_PREFIX=docs
PAPER_PI_ROUTE_STRUCTURE=locale-first
PAPER_PI_ROUTE_MIDDLEWARE=web

Navigation Structure

Define your documentation navigation in config/paper-pi.php:

'navigation' => [
    'en' => [
        'Getting Started' => [
            'Introduction' => '/en/docs',
            'Installation' => '/en/docs/installation',
            'Configuration' => '/en/docs/configuration',
        ],
        'Advanced Topics' => [
            'Caching' => '/en/docs/advanced/caching',
            'Queues' => '/en/docs/advanced/queues',
        ],
    ],
    'es' => [
        'Primeros Pasos' => [
            'Introducción' => '/es/docs',
            'Instalación' => '/es/docs/installation',
        ],
    ],
],

Customization

URL Structure Customization

Paper-Pi offers flexible URL structures to fit your application's needs.

Choosing Your Route Structure

Paper-Pi supports two route structure patterns:

1. Prefix-First (Default) - Best for admin panels

/{route_prefix}/{locale}/{path}

Examples:
- /docs/en/installation
- /admin/docs/en/installation
- /panel/help/en/getting-started

2. Locale-First - Best for public documentation sites

/{locale}/{route_prefix}/{path}

Examples:
- /en/docs/installation
- /en/admin/docs/installation
- /es/help/getting-started

Configuring Route Structure

Environment Variable:

PAPER_PI_ROUTE_STRUCTURE=prefix-first   # Default
# OR
PAPER_PI_ROUTE_STRUCTURE=locale-first

Config File:

// config/paper-pi.php
'route_structure' => 'prefix-first',  // or 'locale-first'

Nested Under Admin Panel

To place documentation under /admin with authentication:

For Laravel Wind / Orchid Platform:

PAPER_PI_ROUTE_PREFIX=admin/docs
PAPER_PI_ROUTE_STRUCTURE=prefix-first
PAPER_PI_ROUTE_MIDDLEWARE=web,auth,orchid

This creates URLs like:

/admin/docs/en/docs (prefix-first)
/admin/docs/en/docs/installation

For Public Multi-Locale Sites:

PAPER_PI_ROUTE_PREFIX=docs
PAPER_PI_ROUTE_STRUCTURE=locale-first
PAPER_PI_ROUTE_MIDDLEWARE=web

This creates URLs like:

/en/docs (locale-first)
/en/docs/installation
/es/docs/installation

URL Helper Functions

Use the helper functions to generate proper URLs in your config:

// config/paper-pi.php
'navigation' => [
    'en' => [
        'Getting Started' => [
            'Introduction' => paper_pi_route('en', 'docs'),
            'Installation' => paper_pi_route('en', 'docs', 'installation'),
            'Configuration' => paper_pi_route('en', 'docs', 'configuration'),
        ],
        'Advanced' => [
            'Caching' => paper_pi_route('en', 'docs', 'advanced/caching'),
            'Queues' => paper_pi_route('en', 'docs', 'advanced/queues'),
        ],
    ],
],

Available Helper Functions

paper_pi_url($locale, $path) - Generate full URL path

paper_pi_url('en', 'docs/installation')
// Returns: /docs/en/docs/installation
// OR: /admin/docs/en/docs/installation (if route_prefix is 'admin/docs')

paper_pi_route($locale, $section, $page) - Generate section-based URL

paper_pi_route('en', 'docs', 'installation')
// Returns: /docs/en/docs/installation

Real-World Examples

Laravel Wind / Orchid Admin Panel:

PAPER_PI_ROUTE_PREFIX=admin/docs
PAPER_PI_ROUTE_STRUCTURE=prefix-first
PAPER_PI_ROUTE_MIDDLEWARE=web,auth,orchid

URLs: /admin/docs/en/installation

SaaS Multi-Tenant Documentation:

PAPER_PI_ROUTE_PREFIX=panel/docs
PAPER_PI_ROUTE_STRUCTURE=prefix-first
PAPER_PI_ROUTE_MIDDLEWARE=web,auth,tenant

URLs: /panel/docs/en/getting-started

Public Documentation Site:

PAPER_PI_ROUTE_PREFIX=docs
PAPER_PI_ROUTE_STRUCTURE=locale-first
PAPER_PI_ROUTE_MIDDLEWARE=web

URLs: /en/docs/installation, /es/docs/installation

Knowledge Base:

PAPER_PI_ROUTE_PREFIX=help
PAPER_PI_ROUTE_STRUCTURE=locale-first
PAPER_PI_ROUTE_MIDDLEWARE=web

URLs: /en/help/faq, /fr/help/contact

Comparison:

Structure	Route Pattern	Example URL	Best For
`prefix-first`	`/{prefix}/{locale}/{path}`	`/admin/docs/en/installation`	Admin panels, nested routes
`locale-first`	`/{locale}/{prefix}/{path}`	`/en/docs/installation`	Public docs, SEO-friendly

Customizing Views

After publishing views, you can customize:

resources/views/vendor/paper-pi/layout.blade.php - Main layout
resources/views/vendor/paper-pi/docs.blade.php - Documentation page template
resources/views/vendor/paper-pi/partials/navigation.blade.php - Navigation sidebar

Custom Styling

The default views include basic styling. You can:

Inline CSS: Edit the <style> blocks in published views

External CSS: Add your own stylesheet in layout.blade.php:

<link rel="stylesheet" href="{{ asset('css/docs.css') }}">

Tailwind/Bootstrap: Remove default styles and use your preferred framework
Match Existing Layout: Extend your app's existing layout instead of using the default

Extending Your Existing Layout

Instead of the default layout, extend your app's layout:

{{-- resources/views/vendor/paper-pi/layout.blade.php --}}
@extends('layouts.app')

@section('content')
    <div class="documentation-wrapper">
        @yield('paper-pi-content')
    </div>
@endsection

{{-- resources/views/vendor/paper-pi/docs.blade.php --}}
@extends('paper-pi::layout')

@section('paper-pi-content')
    <div class="docs-container">
        <aside class="docs-sidebar">
            @include('paper-pi::partials.navigation')
        </aside>
        
        <main class="docs-content">
            <article>
                {!! $content !!}
            </article>
            
            @if($edit)
                <a href="{{ $edit }}" target="_blank" rel="noopener">
                    Edit this page on GitHub
                </a>
            @endif
        </main>
    </div>
@endsection

Custom Routes

If you published routes to routes/paper-pi.php, you can customize the routing logic, add middleware, or create additional documentation-related routes.

YAML Front Matter

YAML front matter is metadata at the top of your markdown files, enclosed by triple dashes (---). It's like adding file properties that tell the application extra information about the page.

Basic Structure

All markdown files should include YAML front matter at the top:

---
title: Page Title
description: SEO-friendly description
keywords: comma, separated, keywords
---

Your markdown content starts here...

How It Works

The package:

Reads your markdown file
Extracts the YAML (between the --- markers)
Parses it into a PHP array
Makes it available in your Blade views as variables
Converts the remaining markdown to HTML

Complete Example

docs/en/docs/installation.md:

---
title: Installation Guide
description: Learn how to install our package in 5 minutes
keywords: installation, setup, composer, laravel
author: Jonathan Aller
difficulty: beginner
estimated_time: 5 minutes
---

## Installation

Run this command to install the package:

\```bash
composer require your/package
\```

In your Blade view, you'll have access to:

{{ $title }}           <!-- Installation Guide -->
{{ $description }}     <!-- Learn how to install... -->
{{ $author }}          <!-- Jonathan Aller -->
{{ $difficulty }}      <!-- beginner -->
{{ $content }}         <!-- Rendered HTML from markdown -->

Field Reference

Required fields:

title: Page title (used in <title> tag and <h1>)

Optional SEO fields:

description: Meta description tag
keywords: Meta keywords tag

Optional fields:

redirect: Redirect URL (e.g., /en/docs/new-location)
author: Content author name
date: Publication date
section: Documentation section
tags: Array of tags
Any custom fields you need!

YAML Syntax Examples

---
# Simple strings
title: Getting Started

# Strings with special characters (use quotes)
title: "Using: Special Characters & Symbols"

# Numbers
page_number: 1
price: 19.99

# Booleans
published: true
featured: false

# Arrays (two ways)
tags: [laravel, php, documentation]

# Or multiline:
tags:
  - laravel
  - php
  - documentation

# Nested objects
author:
  name: Jonathan Aller
  email: j@example.com
  role: Lead Developer

# Dates
published_at: 2025-10-09

# Multiline strings
description: |
  This is a long description
  that spans multiple lines
  and preserves formatting.
---

Custom Fields for Your Use Case

You can add ANY custom fields and access them in your views:

---
title: Recipe Documentation
difficulty: advanced
prep_time: 20 minutes
cook_time: 35 minutes
servings: 12
featured_image: /images/recipe.jpg
ingredients_count: 15
---

Then in your Blade template:

<div class="recipe-meta">
    <span>Difficulty: {{ $difficulty }}</span>
    <span>Prep: {{ $prep_time }}</span>
    <span>Cook: {{ $cook_time }}</span>
    <span>Serves: {{ $servings }}</span>
</div>

Syntax Highlighting

Code blocks are automatically highlighted using laravelsu/highlight:

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;

class Post extends Model
{
    protected $fillable = ['title', 'content'];
}
```

Supported languages: PHP, JavaScript, Python, Bash, SQL, JSON, YAML, HTML, CSS, and more.

Multi-Locale Support

Adding a New Locale

Add to config/paper-pi.php:
```
'locales' => ['en', 'es', 'fr', 'de'],
```
Create documentation directory:
```
mkdir -p docs/es/docs
```

Add translated markdown files:

docs/es/docs/index.md
docs/es/docs/installation.md

Add navigation structure:

'navigation' => [
    'es' => [
        'Primeros Pasos' => [
            'Introducción' => '/es/docs',
        ],
    ],
],

Locale Switching

Add locale switcher to your layout:

<nav>
    @foreach(config('paper-pi.locales') as $locale)
        <a href="/{{ $locale }}/docs">{{ strtoupper($locale) }}</a>
    @endforeach
</nav>

Orchid Platform Integration

Paper-Pi includes built-in support for the Orchid Platform admin interface, allowing you to display documentation as native Orchid Screens.

Features

Orchid Screen Architecture - Uses proper Screen class with query/layout methods
Command Bar Actions - Automatic "Edit on GitHub" button in header
Responsive Sidebar Navigation - Bootstrap grid layout that works with Orchid
Turbo Compatible - Works seamlessly with Orchid's page transitions
Customizable Styling - Matches your Orchid theme colors
Authentication Ready - Works with Orchid's platform middleware

Quick Setup

1. Enable Orchid integration in your .env:

PAPER_PI_ORCHID_AUTO_LOAD_ROUTES=true
PAPER_PI_ROUTE_PREFIX=admin/docs
PAPER_PI_ROUTE_STRUCTURE=prefix-first

2. Publish Orchid views (optional for customization):

php artisan vendor:publish --tag=paper-pi-orchid-views

3. Add documentation menu item in your app/Orchid/PlatformProvider.php:

use Orchid\Screen\Actions\Menu;

public function menu(): array
{
    return [
        Menu::make('Documentation')
            ->icon('bs.book')
            ->url('/admin/docs/en')
            ->title('Resources'),
        
        // ... other menu items
    ];
}

4. Access documentation at /admin/docs/en

Orchid vs Standard Routes

Paper-Pi provides two integration modes:

Mode	Route Type	Best For	URL Pattern
Standard	Regular routes	Public docs, simple sites	`/docs/en/installation`
Orchid	Screen routes	Admin panels, authenticated	`/admin/docs/en/installation`

Standard Mode:

PAPER_PI_AUTO_LOAD_ROUTES=true

Orchid Mode:

PAPER_PI_ORCHID_AUTO_LOAD_ROUTES=true

You can use both modes simultaneously if needed!

Customizing Orchid Views

After publishing Orchid views:

php artisan vendor:publish --tag=paper-pi-orchid-views

Customize the view at:

resources/views/vendor/paper-pi/orchid/docs-content.blade.php

The view uses Bootstrap grid and Orchid's styling conventions. You can:

Change colors to match your brand
Adjust sidebar width and styling
Modify navigation structure
Add custom header/footer elements

Manual Orchid Integration

If you prefer manual setup:

1. Publish routes:

php artisan vendor:publish --tag=paper-pi-orchid-routes

2. Include in your routes/platform.php:

require __DIR__.'/paper-pi-orchid.php';

3. Customize the DocumentationScreen class if needed

Example: Laravel Wind Integration

For a complete Orchid integration like Laravel Wind:

# .env
PAPER_PI_ORCHID_AUTO_LOAD_ROUTES=true
PAPER_PI_ROUTE_PREFIX=admin/docs
PAPER_PI_ROUTE_STRUCTURE=prefix-first
PAPER_PI_ROUTE_MIDDLEWARE=web,platform
PAPER_PI_EDIT_REPOSITORY=https://github.com/BakeMorePies/laravel-wind
PAPER_PI_EDIT_BRANCH=main
PAPER_PI_EDIT_PATH=docs

// config/paper-pi.php
'navigation' => [
    'en' => [
        'Getting Started' => [
            'Introduction' => paper_pi_route('en', 'docs'),
            'Creating Projects' => paper_pi_route('en', 'docs', 'creating-projects'),
        ],
        'User Guide' => [
            'Managing Openings' => paper_pi_route('en', 'docs', 'managing-openings'),
            'Wind Calculations' => paper_pi_route('en', 'docs', 'calculations'),
        ],
    ],
],

Testing

The package works seamlessly with Laravel's testing tools:

public function test_documentation_page_loads()
{
    $response = $this->get('/en/docs');
    
    $response->assertStatus(200);
    $response->assertSee('Getting Started');
}

public function test_documentation_page_not_found()
{
    $response = $this->get('/en/docs/non-existent');
    
    $response->assertStatus(404);
}

Requirements

PHP 8.1 or higher
Laravel 10.x or 11.x
symfony/yaml ^6.0 or ^7.0
laravelsu/highlight dev-main

Credits

This package was extracted from the Orchid Platform documentation system and refactored into a standalone, reusable Laravel package with a delicious pi-themed twist.

Original concept and implementation by Orchid Software
Package extraction and refactoring by Bake More Pies

License

MIT License. See LICENSE file for details.

Support

For issues, questions, or contributions, please visit:

GitHub: https://github.com/BakeMorePies/paper-pi
Email: it@bakemorepies.com

Changelog

Version 1.0.0

Initial release
Markdown to HTML conversion
YAML front matter support
Multi-locale support
Syntax highlighting
Configurable routing
Publishable views and config

Made with by the BakeMorePies Dev team

Turning ideas into reality, one commit at a time

bakemorepies / paper-pi

Maintainers

Details

README

Paper-Pi

Features

Installation

Step 1: Install via Composer

Step 2: Publish Configuration

Step 3: Configure Filesystem Disk

Step 4: Create Documentation Directory

Step 5: Publish Routes (Optional)

Step 6: Publish Views (Optional)

Usage

Creating Documentation Files

Directory Structure

Accessing Documentation

Programmatic Usage

Configuration

Basic Configuration

Environment Variables

Navigation Structure

Customization

URL Structure Customization

Choosing Your Route Structure

Configuring Route Structure

Nested Under Admin Panel

URL Helper Functions

Available Helper Functions

Real-World Examples

Customizing Views

Custom Styling

Extending Your Existing Layout

Custom Routes

YAML Front Matter

Basic Structure

How It Works

Complete Example

Field Reference

YAML Syntax Examples

Custom Fields for Your Use Case

Syntax Highlighting

Multi-Locale Support

Adding a New Locale

Locale Switching

Orchid Platform Integration

Features

Quick Setup

Orchid vs Standard Routes

Customizing Orchid Views

Manual Orchid Integration

Example: Laravel Wind Integration

Testing

Requirements

Credits

License

Support

Changelog

Version 1.0.0