PHPackages                             oi-lab/oi-laravel-documentation - 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. [Utility & Helpers](/categories/utility)
4. /
5. oi-lab/oi-laravel-documentation

ActiveLibrary[Utility & Helpers](/categories/utility)

oi-lab/oi-laravel-documentation
===============================

A Laravel package for managing markdown-based documentation with hierarchical navigation and search

v1.0.8(3w ago)1506↓85.9%MITPHPPHP ^8.3

Since Nov 9Pushed 3w agoCompare

[ Source](https://github.com/oi-lab/oi-laravel-documentation)[ Packagist](https://packagist.org/packages/oi-lab/oi-laravel-documentation)[ RSS](/packages/oi-lab-oi-laravel-documentation/feed)WikiDiscussions main Synced 1w ago

READMEChangelog (1)Dependencies (5)Versions (11)Used By (0)

[![OI Laravel TypeScript Generator](./assets/github-preview.png)](./assets/github-preview.png)

OiLab Laravel Documentation
===========================

[](#oilab-laravel-documentation)

[![Latest Version on Packagist](https://camo.githubusercontent.com/b359d406834db253c138d18f1debfdca3953e7c3ccca7849b120a0a439e869e9/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f692d6c61622f6f692d6c61726176656c2d646f63756d656e746174696f6e2e737667)](https://packagist.org/packages/oi-lab/oi-laravel-documentation)[![Total Downloads](https://camo.githubusercontent.com/935a8bc94a3d63e703ed7312207ac53a92c1ea3fe5812ca32c41a1ac7d614cdf/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f692d6c61622f6f692d6c61726176656c2d646f63756d656e746174696f6e2e737667)](https://packagist.org/packages/oi-lab/oi-laravel-documentation)[![Tests](https://camo.githubusercontent.com/f6a12303ba0357de3b594e8495b53a90202cc44f97f9c0f0528556baa14011bf/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6f692d6c61622f6f692d6c61726176656c2d646f63756d656e746174696f6e2f74657374732e796d6c3f6c6162656c3d7465737473)](https://github.com/oi-lab/oi-laravel-documentation/actions)[![License](https://camo.githubusercontent.com/c7c1dbaafb6452cd64a0628bb9386c447def356f98ba7fcbe0523516d10bb05d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6f692d6c61622f6f692d6c61726176656c2d646f63756d656e746174696f6e)](LICENSE)

A Laravel package for managing markdown-based documentation with hierarchical navigation and full-text search.

Features
--------

[](#features)

- **Markdown-based** - Write documentation in simple markdown files
- **Hierarchical navigation** - Organize content with sections and subsections
- **Full-text search** - Search across all documentation with scoring
- **Auto-generated navigation** - Build navigation from file structure and frontmatter
- **YAML frontmatter** - Add metadata to documentation pages
- **Table of contents** - Automatically extract headings
- **Link transformation** - Convert relative markdown links to route URLs
- **Adjacent page navigation** - Previous/Next page links
- **React components** - Pre-built Inertia.js + React components for documentation UI, installed into a configurable directory
- **Syntax highlighting** - Code blocks with Shiki syntax highlighting
- **Interactive installation** - Installation wizard with package manager detection (pnpm/npm/yarn) and access control prompts

Requirements
------------

[](#requirements)

- PHP 8.3 or higher
- Laravel 11.x, 12.x or 13.x
- Inertia.js with React
- Node.js with a JS package manager (pnpm, npm or yarn)

Installation
------------

[](#installation)

### 1. Install via Composer

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

```
composer require oi-lab/oi-laravel-documentation
```

### 2. Run the Installation Wizard

[](#2-run-the-installation-wizard)

```
php artisan doc:install
```

The interactive installation wizard will:

- ✓ Publish the configuration file to `config/oi-laravel-documentation.php`
- ✓ Publish routes to `routes/documentation.php`
- ✓ Ask whether the documentation is public or restricted by a middleware
- ✓ Create `resources/markdown/docs/` with sample documentation (customizable path)
- ✓ Install React components (layouts, pages, components) into a configurable directory
- ✓ Detect and install missing JS packages with your package manager
- ✓ Install ShadCN UI components (sonner for toast notifications)
- ✓ Guide you through the setup process

**Documentation Access:**

When the config file is published, the wizard asks how the documentation should be reached:

- **Public** - keeps the route on the `web` middleware only.
- **Authenticated users only** - adds the `auth` middleware.
- **Custom middleware** - prompts for one or more middleware names (comma separated).

Your choice is written to `route.middleware` in `config/oi-laravel-documentation.php`; you can edit it there anytime.

**Package Manager:**

When JS dependencies (or ShadCN components) need to be installed, the wizard asks which package manager to use and lets you pick between `pnpm`, `npm` and `yarn`. The one detected in your project is preselected by default:

- the `packageManager` field in `package.json`, if present;
- otherwise the lockfile found in the project (`pnpm-lock.yaml`, `yarn.lock` or `package-lock.json`);
- falling back to `npm`.

The corresponding commands are used under the hood (`pnpm add` / `npm install` / `yarn add` for dependencies, `pnpm dlx` / `npx` / `yarn dlx` for ShadCN).

**Installation Options:**

- Use `--force` to overwrite existing files
- Skip individual steps if already installed
- Choose which files to overwrite when conflicts occur

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

[](#configuration)

### Publishing the Configuration File

[](#publishing-the-configuration-file)

If you need to customize the configuration, you can publish the config file separately:

```
php artisan vendor:publish --tag=oi-documentation-config
```

This will create `config/oi-laravel-documentation.php` in your application.

### Configuration Options

[](#configuration-options)

The configuration file `config/oi-laravel-documentation.php` allows you to customize:

```
return [
    // Path to documentation files (relative to base_path())
    // You can customize this to store docs anywhere, e.g., 'resources/docs'
    'docs_path' => 'resources/markdown/docs',

    // Where the published React components are installed (keep it under resources/js/)
    'components_path' => 'resources/js/components/documentation',

    // Navigation and search index filenames
    'navigation_file' => 'navigation.json',
    'search_index_file' => 'search-index.json',

    // Route configuration
    'route' => [
        'enabled' => true,
        'prefix' => 'documentation',
        'middleware' => ['web'], // e.g. ['web', 'auth'] to require authentication
    ],

    // Search settings
    'search' => [
        'min_query_length' => 2,
        'excerpt_length' => 150,
        'excerpt_context' => 50,
    ],
];
```

### Custom Documentation Path

[](#custom-documentation-path)

You can customize the location of your documentation files by changing the `docs_path` setting:

```
// config/oi-laravel-documentation.php
'docs_path' => 'resources/docs', // Custom path
```

All commands (`doc:gen-nav`, `doc:gen-index`) will automatically use your custom path.

Documentation Structure
-----------------------

[](#documentation-structure)

### Directory Layout

[](#directory-layout)

```
resources/markdown/docs/
├── meta.json                    # Root metadata
├── navigation.json              # Auto-generated navigation
├── search-index.json            # Auto-generated search index
└── getting-started/
    ├── meta.json                # Section metadata
    ├── _index.md                # Section introduction
    └── installation.md          # Page

```

### Section meta.json

[](#section-metajson)

Each section directory should contain a `meta.json` file:

```
{
    "title": "Getting Started",
    "description": "Introduction and basic concepts",
    "order": 1,
    "type": "section"
}
```

### Markdown Frontmatter

[](#markdown-frontmatter)

Each markdown file should have YAML frontmatter:

```
---
title: Installation
description: How to install and configure
section: getting-started
order: 2
---

# Installation

Your content here...
```

### 3. Register Routes

[](#3-register-routes)

Add the documentation routes to your `bootstrap/app.php`:

```
->withRouting(
    web: __DIR__.'/../routes/web.php',
    commands: __DIR__.'/../routes/console.php',
    health: '/up',
    then: function () {
        Route::middleware('web')
            ->group(base_path('routes/documentation.php'));
    },
)
```

### 4. Build Frontend Assets

[](#4-build-frontend-assets)

After installation, build your frontend assets:

```
npm run build
# or for development
npm run dev
```

PHP Dependencies
----------------

[](#php-dependencies)

The package requires these Composer packages (automatically resolved):

```
{
  "illuminate/support": "^11.0|^12.0|^13.0",
  "symfony/yaml": "^6.0|^7.0"
}
```

JS Dependencies
---------------

[](#js-dependencies)

The package requires these JS packages (automatically installed by the wizard, using the package manager you select — `pnpm`, `npm` or `yarn`):

```
{
  "@inertiajs/react": "^2.0.0",
  "react-markdown": "^9.0.0",
  "remark-gfm": "^4.0.0",
  "rehype-raw": "^7.0.0",
  "rehype-sanitize": "^6.0.0",
  "slugify": "^1.6.6",
  "shiki": "^1.0.0",
  "lucide-react": "^0.460.0",
  "usehooks-ts": "^3.1.1",
  "class-variance-authority": "^0.7.0"
}
```

ShadCN UI Components
--------------------

[](#shadcn-ui-components)

The package uses ShadCN UI components for the user interface. The installation wizard automatically installs the required components using the ShadCN CLI, run through your selected package manager:

```
# pnpm
pnpm dlx shadcn@latest add sonner

# npm
npx shadcn@latest add sonner

# yarn
yarn dlx shadcn@latest add sonner
```

**Currently installed components:**

- `sonner` - Toast notifications for flash messages

**Adding more components:**

To add additional ShadCN UI components to the installation, edit the `$shadcnComponents` array in `src/Console/Commands/InstallDocumentation.php`:

```
private array $shadcnComponents = [
    'sonner',
    'button',
    'dialog',
    // Add more components as needed
];
```

The wizard will automatically install them when running `php artisan doc:install`.

Commands
--------

[](#commands)

### Add a Documentation Page

[](#add-a-documentation-page)

Create a new markdown page interactively. The command asks which folder the page belongs to (with a selection prompt) and lets you create a new folder on the fly:

```
php artisan doc:add-page

# Regenerate navigation and search index automatically afterwards
php artisan doc:add-page --regenerate
```

It writes a markdown file with frontmatter into the chosen folder (and creates a `meta.json` for any new folder), then optionally runs `doc:gen-nav` and `doc:gen-index`.

### Generate Navigation

[](#generate-navigation)

Generate the navigation structure from your documentation files:

```
php artisan doc:gen-nav
```

This scans `resources/markdown/docs/` and creates `navigation.json`.

### Generate Search Index

[](#generate-search-index)

Generate the search index for full-text search:

```
php artisan doc:gen-index
```

This creates `search-index.json` from all documentation pages.

### Install Documentation

[](#install-documentation)

Install the package with the interactive wizard:

```
php artisan doc:install

# Force overwrite existing files
php artisan doc:install --force
```

Routes
------

[](#routes)

The package registers these routes (with configurable prefix):

```
GET /documentation              # Index page
GET /documentation/search       # Search endpoint
GET /documentation/{slug}       # Show documentation page
```

Usage in Controllers
--------------------

[](#usage-in-controllers)

Inject the `DocumentationService`:

```
use OiLab\LaravelDocumentation\Services\DocumentationService;

class CustomController extends Controller
{
    public function __construct(
        public DocumentationService $documentationService
    ) {}

    public function index()
    {
        $navigation = $this->documentationService->getNavigation();
        $document = $this->documentationService->getDocument('getting-started');
        $adjacent = $this->documentationService->getAdjacentPages('getting-started');

        // ...
    }
}
```

React Components
----------------

[](#react-components)

The installation wizard automatically installs these React components:

### Components (`resources/js/components/documentation/`)

[](#components-resourcesjscomponentsdocumentation)

- `documentation-markdown-content.tsx` - Renders markdown with syntax highlighting
- `documentation-navigation.tsx` - Hierarchical navigation sidebar
- `documentation-search.tsx` - Search interface with live results
- `documentation-toc.tsx` - Table of contents sidebar
- `documentation-heading.tsx` - Typography component with `size` variants (`xs`, `sm`, `default`, `lg`) built with `cva`, the same way ShadCN UI components are
- `documentation-header.tsx` - Sticky header (logo, search, navigation links)
- `documentation-footer.tsx` - Footer
- `sign.tsx` - Signature SVG component

> The components directory is configurable. Change `components_path` in `config/oi-laravel-documentation.php` to install them elsewhere (keep it under `resources/js/` so the `@/` import alias keeps working — the wizard rewrites the imports accordingly).

### Layouts (`resources/js/layouts/`)

[](#layouts-resourcesjslayouts)

- `documentation-layout.tsx` - Main documentation layout wrapper (composes `documentation-header.tsx` + `documentation-footer.tsx`, mirroring the Laravel React starter kit layout structure)

### Pages (`resources/js/pages/documentation/`)

[](#pages-resourcesjspagesdocumentation)

- `index.tsx` - Documentation homepage
- `show.tsx` - Documentation page viewer

### Props Available

[](#props-available)

**Index page:**

```
{
    navigation: NavigationStructure
}
```

**Show page:**

```
{
    document: {
        frontmatter: Record,
        markdown: string,
        tableOfContents: Array
    },
    navigation: NavigationStructure,
    slug: string,
    previousPage: PageItem | null,
    nextPage: PageItem | null
}
```

### Hooks (`resources/js/hooks/`)

[](#hooks-resourcesjshooks)

- `use-flash-messages.tsx` - Hook for displaying flash messages using Sonner toasts

**Note:** The components use ShadCN UI. The installation wizard automatically installs the required components (`sonner`). If you need additional ShadCN UI components, you can install them manually:

```
npx shadcn@latest add button
npx shadcn@latest add input
npx shadcn@latest add separator
```

### Using Toast Notifications

[](#using-toast-notifications)

The package includes a `useFlashMessages` hook that automatically displays Laravel flash messages as toast notifications using Sonner. The hook is already integrated in the `documentation-layout.tsx`.

To send flash messages from your Laravel controllers:

```
return redirect()->route('documentation.show', $slug)
    ->with('success', 'Documentation updated successfully!');

return redirect()->back()
    ->with('error', 'Failed to update documentation');

return redirect()->back()
    ->with('info', 'Documentation is being processed');
```

The toast notifications will automatically appear with the appropriate styling (success, error, info).

Workflow
--------

[](#workflow)

1. Write markdown files in `resources/markdown/docs/`
2. Add `meta.json` files for sections
3. Run `php artisan doc:gen-nav` to generate navigation
4. Run `php artisan doc:gen-index` to generate search index
5. Access documentation at `/documentation`

Link Transformation
-------------------

[](#link-transformation)

The package automatically transforms relative markdown links:

```
[Installation](installation.md)
```

Becomes:

```
[Installation](/documentation/getting-started/installation)
```

Search
------

[](#search)

The search endpoint scores results based on:

- Title match: +10 points
- Description match: +5 points
- Heading match: +3 points
- Content match: +1 point

Results are sorted by score and include contextual excerpts.

Changelog
---------

[](#changelog)

See [CHANGELOG.md](CHANGELOG.md) for a list of notable changes.

License
-------

[](#license)

This package is open-source software licensed under the [MIT license](LICENSE).

Credits
-------

[](#credits)

**[Olivier Lacombe](https://www.olacombe.com)** - Creator and maintainer

Olivier is a Product & Technology Director based in Montpellier, France, with over 20 years of experience innovating in UX/UI and emerging technologies. He specializes in guiding enterprises toward cutting-edge digital solutions, combining user-centered design with continuous optimization and artificial intelligence integration.

**Projects & Resources:**

- [OnAI](https://onai.olacombe.com) - Training courses and masterclasses on generative AI for businesses
- [Promptr](https://promptr.olacombe.com) - Prompt engineering Management Platform

Support
-------

[](#support)

For support, please open an issue on the [GitHub repository](https://github.com/oi-lab/oi-laravel-ts/issues).

###  Health Score

47

—

FairBetter than 93% of packages

Maintenance95

Actively maintained with recent releases

Popularity20

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity56

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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 ~23 days

Recently: every ~4 days

Total

9

Last Release

24d ago

PHP version history (2 changes)v1.0.0PHP ^8.2

v1.0.3PHP ^8.3

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/369876?v=4)[Olivier Lacombe](/maintainers/olacombe)[@olacombe](https://github.com/olacombe)

---

Top Contributors

[![olacombe](https://avatars.githubusercontent.com/u/369876?v=4)](https://github.com/olacombe "olacombe (18 commits)")

###  Code Quality

TestsPest

### Embed Badge

![Health badge](/badges/oi-lab-oi-laravel-documentation/health.svg)

```
[![Health](https://phpackages.com/badges/oi-lab-oi-laravel-documentation/health.svg)](https://phpackages.com/packages/oi-lab-oi-laravel-documentation)
```

###  Alternatives

[craftcms/cms

Craft CMS

3.6k3.6M2.9k](/packages/craftcms-cms)[laravel/sail

Docker files for running a basic Laravel application.

1.9k199.2M1.2k](/packages/laravel-sail)[psalm/plugin-laravel

Psalm plugin for Laravel

3325.1M337](/packages/psalm-plugin-laravel)[friendsoftypo3/content-blocks

TYPO3 CMS Content Blocks - Content Types API | Define reusable components via YAML

101466.4k44](/packages/friendsoftypo3-content-blocks)[flarum/core

Delightfully simple forum software.

261.4M2.2k](/packages/flarum-core)[rcsofttech/audit-trail-bundle

Enterprise-grade, high-performance Symfony audit trail bundle. Automatically track Doctrine entity changes with split-phase architecture, multiple transports (HTTP, Queue, Doctrine), and sensitive data masking.

1155.2k](/packages/rcsofttech-audit-trail-bundle)

PHPackages © 2026

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