PHPackages                             xoshbin/pertuk - 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. xoshbin/pertuk

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

xoshbin/pertuk
==============

A powerful Laravel documentation package with multi-language support, markdown processing, and beautiful UI

v1.0.2(2mo ago)1880↑57.1%[1 PRs](https://github.com/Xoshbin/pertuk/pulls)MITPHPPHP ^8.4 || ^8.3CI passing

Since Sep 9Pushed 1w agoCompare

[ Source](https://github.com/Xoshbin/pertuk)[ Packagist](https://packagist.org/packages/xoshbin/pertuk)[ Docs](https://github.com/xoshbin/pertuk)[ GitHub Sponsors](https://github.com/:vendor_name)[ RSS](/packages/xoshbin-pertuk/feed)WikiDiscussions main Synced 2d ago

READMEChangelog (10)Dependencies (34)Versions (20)Used By (0)

Pertuk - Laravel Documentation Package
======================================

[](#pertuk---laravel-documentation-package)

[![Latest Version on Packagist](https://camo.githubusercontent.com/2445727114846e729ce8d5cfa91f9db7e3b68bc065df0af311a1756ed0099e94/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f786f736862696e2f70657274756b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/xoshbin/pertuk)[![GitHub Tests Action Status](https://camo.githubusercontent.com/6209b9b5fdf768e54d56aca9df10f26d91f44404dc8070b090cb466f81c198d4/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f786f736862696e2f70657274756b2f72756e2d74657374733f6c6162656c3d7465737473)](https://github.com/xoshbin/pertuk/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/21913407047ca1ca32f0e627ed6ec90742fe3f1c80bddb2ebcfe3e50c35fbd67/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f776f726b666c6f772f7374617475732f786f736862696e2f70657274756b2f6669782d7068702d636f64652d7374796c652d6973737565733f6c6162656c3d636f64652532307374796c65)](https://github.com/xoshbin/pertuk/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/d35c6734573c82cda532c2664f0b8c9d1fc2b4abedb898b9b4d24f720b5df618/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f786f736862696e2f70657274756b2e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/xoshbin/pertuk)

Pertuk is a powerful Laravel documentation package that provides a complete documentation system with multi-language support, markdown processing, search functionality, and a beautiful, responsive UI.

[![img.png](assets/screenshot.jpeg)](assets/screenshot.jpeg)

Features
--------

[](#features)

- 📖 **Premium Markdown**: Full CommonMark and GitHub Flavored Markdown support
- 🎨 **Shiki Syntax Highlighting**: Server-side, VS-Code quality syntax highlighting
- 🌍 **Multi-Language Support**: Built-in support for multiple locales with RTL handling
- 🪴 **Root Locale**: Serve a primary language at the docs root with no URL prefix (VitePress/Starlight style)
- 🔢 **Versioning Support**: Explicit version configuration with a built-in version picker
- 🐙 **GitHub Source**: Render docs directly from any GitHub repository
- 🔍 **Deep Local Search**: Full-content indexing via MiniSearch with relevancy scoring
- 🧩 **Interactive Components**: Built-in support for Tabs and Accordions in Markdown
- 🎨 **Modern UI**: Responsive design with interactive sidebar and dark mode
- 📱 **Mobile Friendly**: Optimized for all device sizes
- 🗂️ **Auto Table of Contents**: Automatic TOC generation from headings
- 💾 **Intelligent Caching**: High-performance document rendering and caching
- 🧭 **Breadcrumbs**: Automatic breadcrumb navigation
- 🏷️ **Front Matter Support**: YAML front matter for metadata
- 💡 **Admonitions**: Support for tip, warning, and danger callouts
- 🚀 **Pre-rendering**: Artisan command to pre-render documentation for maximum speed

Quick Start
-----------

[](#quick-start)

1. Install the package:

```
composer require xoshbin/pertuk
```

2. Publish the assets (JS and CSS):

```
php artisan vendor:publish --tag="pertuk-assets"
```

3. (Optional) Publish the config:

```
php artisan vendor:publish --tag="pertuk-config"
```

4. Create your docs directory and add a markdown file.
5. Visit your docs at `/docs`.

- **Customization**: Publish the views to customize the layout and markup:

```
php artisan vendor:publish --tag="pertuk-views"
```

6. (Optional) Pre-render documentation for performance:

```
php artisan pertuk:build
```

Configuration
-------------

[](#configuration)

```
return [
    // Root folder for documentation files (local source).
    'root' => base_path('docs'),

    // Source driver: 'local' (default) or 'github'.
    'source' => env('PERTUK_SOURCE', 'local'),

    // Per-driver configuration.
    'sources' => [
        'local' => [
            'root' => env('PERTUK_DOCS_LOCAL_ROOT'),
        ],
        'github' => [
            'repo'       => env('PERTUK_DOCS_REPO'),
            'branch'     => env('PERTUK_DOCS_BRANCH', 'main'),
            'path'       => env('PERTUK_DOCS_PATH', 'docs'),
            'token'      => env('PERTUK_DOCS_TOKEN'),
            'cache_path' => storage_path('app/pertuk/github'),
        ],
    ],

    // Locale configuration — mirrors VitePress/Starlight conventions.
    // The 'root' key designates the primary locale whose files live flat
    // at the docs root with no URL prefix. Secondary locales keep /{code}/.
    // Omit 'root' to use classic locale-prefixed mode (docs/en/, docs/ar/).
    'locales' => [
        'root' => ['label' => 'English', 'lang' => 'en', 'dir' => 'ltr'],
        'ar'   => ['label' => 'العربية', 'lang' => 'ar', 'dir' => 'rtl'],
        'ckb'  => ['label' => 'کوردی (سۆرانی)', 'lang' => 'ckb', 'dir' => 'rtl'],
    ],

    // Explicit version list. Empty = no versioning.
    // e.g. ['v1.0', 'v2.0']
    'versions' => [],

    // Default sort order when front matter 'order' is missing.
    'default_order' => 1000,

    // Excluded files or folders (relative to root) for file listing.
    'exclude_directories' => [
        '.DS_Store',
        'README.md',
    ],

    // Cache TTL (seconds) for parsed HTML & metadata.
    'cache_ttl' => 3600,

    // Enable or disable the documentation system.
    'enabled' => true,

    // Route prefix for documentation.
    'route_prefix' => 'docs',

    // Route name prefix.
    'route_name_prefix' => 'pertuk.docs.',

    // Route middleware.
    'middleware' => ['web'],

    // GitHub Repo & Branch for "Edit on GitHub" links.
    'github_repo'   => env('PERTUK_GITHUB_REPO', 'username/repo'),
    'github_branch' => env('PERTUK_GITHUB_BRANCH', 'main'),
    'github_path'   => null,

    // Assets directory (relative to documentation root).
    'assets_path' => 'assets',

    // External links.
    'github_url'  => env('PERTUK_GITHUB_URL', ''),
    'discord_url' => env('PERTUK_DISCORD_URL', ''),
];
```

Directory Structures
--------------------

[](#directory-structures)

### Root locale (flat) — recommended for single-language or GitHub-sourced repos

[](#root-locale-flat--recommended-for-single-language-or-github-sourced-repos)

Inspired by VitePress and Starlight. One locale is designated `root` in config — its files live directly at the docs root with no subdirectory or URL prefix. Secondary locales keep their `/{code}/` prefix.

```
docs/
├── explanation/
│   └── introduction.md     → /docs/explanation/introduction
├── how-to/
│   └── publishing.md       → /docs/how-to/publishing
├── tutorials/
│   └── quick-start.md      → /docs/tutorials/quick-start
└── ar/
    └── explanation/
        └── introduction.md → /docs/ar/explanation/introduction

```

Config:

```
'locales' => [
    'root' => ['label' => 'English', 'lang' => 'en', 'dir' => 'ltr'],
    'ar'   => ['label' => 'العربية', 'lang' => 'ar', 'dir' => 'rtl'],
],
```

### Classic locale-prefixed — all locales in subdirectories

[](#classic-locale-prefixed--all-locales-in-subdirectories)

Omit the `root` key. Every locale, including the primary one, lives in its own subdirectory. This is the legacy behaviour and continues to work unchanged.

```
docs/
├── en/
│   └── getting-started.md  → /docs/en/getting-started
└── ar/
    └── getting-started.md  → /docs/ar/getting-started

```

Config:

```
'locales' => [
    'en' => ['label' => 'English', 'lang' => 'en', 'dir' => 'ltr'],
    'ar' => ['label' => 'العربية', 'lang' => 'ar', 'dir' => 'rtl'],
],
```

### Versioned structure

[](#versioned-structure)

Add version directories above the locale layout. Declare versions explicitly in config — no automatic directory scanning.

```
docs/
├── v1.0/
│   ├── getting-started.md          → /docs/v1.0/getting-started  (root locale)
│   └── ar/
│       └── getting-started.md      → /docs/v1.0/ar/getting-started
└── v2.0/
    └── getting-started.md          → /docs/v2.0/getting-started

```

Config:

```
'locales'  => [
    'root' => ['label' => 'English', 'lang' => 'en', 'dir' => 'ltr'],
    'ar'   => ['label' => 'العربية', 'lang' => 'ar', 'dir' => 'rtl'],
],
'versions' => ['v1.0', 'v2.0'],
```

### Monolingual (single language, no locale UI)

[](#monolingual-single-language-no-locale-ui)

Configure only a `root` locale with no secondary entries. The language picker is hidden automatically.

```
docs/
├── getting-started.md   → /docs/getting-started
└── reference/
    └── api.md           → /docs/reference/api

```

Config:

```
'locales' => [
    'root' => ['label' => 'English', 'lang' => 'en', 'dir' => 'ltr'],
],
'versions' => [],
```

GitHub Source
-------------

[](#github-source)

Pertuk can render markdown stored in a GitHub repository instead of the local filesystem. Set `PERTUK_SOURCE=github` and configure the repo, branch, and path. The package syncs the full directory tree into `storage/app/pertuk/github/` during `pertuk:build` and falls back to on-demand single-file fetches at runtime.

```
PERTUK_SOURCE=github
PERTUK_DOCS_REPO=Xoshbin/asyar-launcher
PERTUK_DOCS_BRANCH=main
PERTUK_DOCS_PATH=docs
# Optional — required for private repos, recommended to avoid the 60/hr anonymous rate limit.
PERTUK_DOCS_TOKEN=ghp_xxx
```

The GitHub source works with all directory structures above — including root locale (flat) layouts. Run `php artisan pertuk:build` as part of your deploy to sync changes.

Migrating from the old locale config
------------------------------------

[](#migrating-from-the-old-locale-config)

If you are upgrading from a version that used `supported_locales`, `default_locale`, `rtl_locales`, and `locale_labels`, replace them with the unified `locales` map. No files need to move if you omit the `root` key.

```
// Before
'supported_locales' => ['en', 'ar'],
'default_locale'    => 'en',
'rtl_locales'       => ['ar'],
'locale_labels'     => ['en' => 'English', 'ar' => 'العربية'],

// After (classic prefix mode — no files to move)
'locales' => [
    'en' => ['label' => 'English', 'lang' => 'en', 'dir' => 'ltr'],
    'ar' => ['label' => 'العربية', 'lang' => 'ar', 'dir' => 'rtl'],
],
'versions' => [],
```

Also replace `exclude_versions` with an explicit `versions` array — list only the versions you want to expose.

If you published the vendor views (`php artisan vendor:publish --tag="pertuk-views"`), re-publish them to get the updated templates, or replace any `route('pertuk.docs.show', ['locale' => ..., 'slug' => ...])` calls with `\Xoshbin\Pertuk\Support\PertukUrl::doc($slug)`.

Front Matter
------------

[](#front-matter)

```
---
title: "Getting Started"
order: 1
---
# Getting Started

Your content here...
```

Interactive Components (Alpine.js)
----------------------------------

[](#interactive-components-alpinejs)

### Tabs

[](#tabs)

```

```php
echo "Hello World";
```

```
console.log("Hello World");
```

``` ### Accordion

[](#accordion)

```

Yes! Publish the views to match your brand.

```

Admonitions
-----------

[](#admonitions)

```
::: tip
This is a helpful tip.
:::

::: warning
Be careful with this setting.
:::

::: danger
This action cannot be undone.
:::
```

Assets & Images
-------------------

[](#assets--images)

Place images in an `assets/` directory at the docs root and reference them with relative paths:

```
![My Feature](../assets/my-feature.png)
```

Pertuk rewrites these paths to `/docs/assets/filename.png` automatically.

**Directory conflict warning:** Do not create a physical `public/docs` directory. In Nginx, physical directories take precedence over Laravel routes, causing `403 Forbidden` errors.

Performance
-----------

[](#performance)

Pre-render all documentation to cache during deployment:

```
php artisan pertuk:build
```

Testing
-------

[](#testing)

```
composer test
```

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Xoshbin](https://github.com/xoshbin)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

49

—

FairBetter than 94% of packages

Maintenance91

Actively maintained with recent releases

Popularity20

Limited adoption so far

Community9

Small or concentrated contributor base

Maturity62

Established project with proven stability

 Bus Factor1

Top contributor holds 93.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~16 days

Total

14

Last Release

85d ago

Major Versions

v0.1.6 → v1.0.02026-04-10

PHP version history (2 changes)0.0.1PHP ^8.4

0.0.4PHP ^8.4 || ^8.3

### Community

Maintainers

![](https://www.gravatar.com/avatar/88844b024c613b0dff2f4355a3ce9938287ec682d1f27964fbee51857b3bd4ff?d=identicon)[khoshbin](/maintainers/khoshbin)

---

Top Contributors

[![Xoshbin](https://avatars.githubusercontent.com/u/1606070?v=4)](https://github.com/Xoshbin "Xoshbin (122 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (6 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (2 commits)")

---

Tags

laraveldocumentationmarkdowndocsmulti-languageXoshbin

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/xoshbin-pertuk/health.svg)

```
[![Health](https://phpackages.com/badges/xoshbin-pertuk/health.svg)](https://phpackages.com/packages/xoshbin-pertuk)
```

###  Alternatives

[dedoc/scramble

Automatic generation of API documentation for Laravel applications.

2.1k11.2M100](/packages/dedoc-scramble)[spatie/laravel-pdf

Create PDFs in Laravel apps

1.0k4.8M47](/packages/spatie-laravel-pdf)[rawilk/profile-filament-plugin

Profile & MFA starter kit for filament.

3914.6k](/packages/rawilk-profile-filament-plugin)[harris21/laravel-fuse

Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures.

44855.7k](/packages/harris21-laravel-fuse)[vormkracht10/laravel-mails

Laravel Mails can collect everything you might want to track about the mails that has been sent by your Laravel app.

24857.5k](/packages/vormkracht10-laravel-mails)[spatie/laravel-markdown-response

Serve markdown versions of your HTML pages to AI agents and bots

7655.9k6](/packages/spatie-laravel-markdown-response)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)