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:

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:

1. Inline CSS: Edit the <style> blocks in published views
2. External CSS: Add your own stylesheet in layout.blade.php:

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

3. Tailwind/Bootstrap: Remove default styles and use your preferred framework
4. 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:

1. Reads your markdown file
2. Extracts the YAML (between the --- markers)
3. Parses it into a PHP array
4. Makes it available in your Blade views as variables
5. 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

1. Add to config/paper-pi.php:

   'locales' => ['en', 'es', 'fr', 'de'],

2. Create documentation directory:

   mkdir -p docs/es/docs

3. Add translated markdown files:

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

4. 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:

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