Download the PHP package xoshbin/pertuk without Composer

Pertuk - Laravel Documentation Package

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.

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

1. Install the package:

2. Publish the assets (JS and CSS):

3. (Optional) Publish the 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:

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

Configuration

Directory Structures

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.

Config:

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.

Config:

Versioned structure

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

Config:

Monolingual (single language, no locale UI)

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

Config:

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.

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

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.

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

Interactive Components (Alpine.js)

Tabs

javascript console.log("Hello World");

Accordion

Admonitions

Assets & Images

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

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

Pre-render all documentation to cache during deployment:

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Xoshbin
• All Contributors

License

The MIT License (MIT). Please see License File for more information.