PHPackages                             bakemorepies/paper-pi - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Parsing & Serialization](/categories/parsing)
4. /
5. bakemorepies/paper-pi

ActiveLibrary[Parsing & Serialization](/categories/parsing)

bakemorepies/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.

v1.3.1(7mo ago)021MITPHPPHP ^8.1|^8.2|^8.3|^8.4

Since Oct 9Pushed 7mo agoCompare

[ Source](https://github.com/BakeMorePies/paper-pi)[ Packagist](https://packagist.org/packages/bakemorepies/paper-pi)[ RSS](/packages/bakemorepies-paper-pi/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (3)Versions (6)Used By (0)

 [![BakeMorePies Logo](https://raw.githubusercontent.com/BakeMorePies/art/refs/heads/master/logos/bmp-horizontal-logo.png)](https://raw.githubusercontent.com/BakeMorePies/art/refs/heads/master/logos/bmp-horizontal-logo.png)

Paper-Pi
========

[](#paper-pi)

[![Latest Stable Version](https://camo.githubusercontent.com/07e7873b805385f8c8ff3da694f37ce8f51d39e3c8d16bb51ad914190d9ad3ba/68747470733a2f2f706f7365722e707567782e6f72672f62616b656d6f7265706965732f70617065722d70692f762f737461626c65)](https://packagist.org/packages/bakemorepies/paper-pi)[![Total Downloads](https://camo.githubusercontent.com/8ce85d3c071431fa6a56393aa0f76478bcc9879fe5fb46f82d3cf7bfc4f504c6/68747470733a2f2f706f7365722e707567782e6f72672f62616b656d6f7265706965732f70617065722d70692f646f776e6c6f616473)](https://packagist.org/packages/bakemorepies/paper-pi)[![License](https://camo.githubusercontent.com/9d53707d41dee1b0f03e75c63239f21e50721effca3e0df4b070d7e9215a8759/68747470733a2f2f706f7365722e707567782e6f72672f62616b656d6f7265706965732f70617065722d70692f6c6963656e7365)](https://packagist.org/packages/bakemorepies/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
--------

[](#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
------------

[](#installation)

### Step 1: Install via Composer

[](#step-1-install-via-composer)

```
composer require bakemorepies/paper-pi
```

The package will be auto-discovered by Laravel.

### Step 2: Publish Configuration

[](#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

[](#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

[](#step-4-create-documentation-directory)

Create your documentation directory structure:

```
mkdir -p docs/en/docs
```

### Step 5: Publish Routes (Optional)

[](#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)

[](#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
-----

[](#usage)

### Creating Documentation Files

[](#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

[](#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

[](#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

[](#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
-------------

[](#configuration)

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

[](#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

[](#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
-------------

[](#customization)

### URL Structure Customization

[](#url-structure-customization)

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

#### Choosing Your Route Structure

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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:**

StructureRoute PatternExample URLBest 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

[](#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

[](#custom-styling)

The default views include basic styling. You can:

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

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

[](#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')

        @yield('paper-pi-content')

@endsection
```

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

@section('paper-pi-content')

            @include('paper-pi::partials.navigation')

                {!! $content !!}

            @if($edit)

                    Edit this page on GitHub

            @endif

@endsection
```

### Custom Routes

[](#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)

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

[](#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

[](#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

[](#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 }}
{{ $description }}
{{ $author }}
{{ $difficulty }}
{{ $content }}
```

### Field Reference

[](#field-reference)

**Required fields:**

- `title`: Page title (used in `` tag and ``)

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

[](#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

[](#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:

```

    Difficulty: {{ $difficulty }}
    Prep: {{ $prep_time }}
    Cook: {{ $cook_time }}
    Serves: {{ $servings }}

```

Syntax Highlighting
-------------------

[](#syntax-highlighting)

Code blocks are automatically highlighted using [laravelsu/highlight](https://github.com/laravelsu/highlight):

```
```php