README

A beautiful, feature-rich documentation package for Laravel applications with dark/light mode support, nested navigation, and live markdown rendering.

Features

🎨 Beautiful UI - Clean, modern interface with Tailwind CSS
🌓 Dark/Light Mode - Automatic theme switching with localStorage persistence
📁 Nested Navigation - Support for deeply nested documentation structure
🔍 Smart Routing - Case-insensitive, slugified URLs
📝 GitHub Flavored Markdown - Full GFM support with syntax highlighting
⚡ React/Inertia - Smooth SPA experience with Inertia.js
🎯 Index File Support - Customizable naming and sorting for README/index files
🔒 Environment Control - Enable/disable based on environment
🎨 Syntax Highlighting - Beautiful code blocks with highlight.js

Requirements

PHP 8.1 or higher
Laravel 11.x or 12.x
Node.js & NPM (for frontend assets)
Inertia.js with React

Installation

1. Install via Composer

composer require buzekpdev/laravel-docsites

2. Publish Configuration

php artisan vendor:publish --tag=docsites-config

3. Publish Assets

# Publish React components
php artisan vendor:publish --tag=docsites-views

# Publish CSS files
php artisan vendor:publish --tag=docsites-css

4. Install NPM Dependencies

npm install react-markdown remark-gfm rehype-highlight rehype-raw highlight.js

5. Build Assets

npm run build
# or for development
npm run dev

6. Create Documentation Directory

Create a docs/ folder in your project root and add your markdown files:

docs/
├── API/
│   ├── authentication.md
│   └── README.md
└── Laravel/
    ├── installation.md
    ├── index.md
    └── Http/
        ├── routing.md
        ├── controllers.md
        └── middleware.md

Configuration

PHP Configuration

Edit config/docsites.php to customize your documentation:

return [
    // Enable/disable the documentation routes
    'enabled' => env('DOCSITES_ENABLED', true),

    // Environments where docs are available
    'allowed_environments' => ['local', 'staging'],

    // Route prefix (e.g., /docs)
    'route_prefix' => 'docs',

    // Middleware to apply
    'middleware' => ['web'],

    // Documentation directory path
    'docs_path' => base_path('docs'),

    // Index file configuration
    'index_file' => [
        'name' => 'Overview',  // Display name for README.md/index.md
        'sort' => 'prepend',   // 'prepend' or 'append'
    ],
];

JSON Configuration (Optional)

Create a docs/docsites.json file to customize display names and formatting:

{
    "$schema": "./docsites.schema.json",
    "alias": {
        "api": "API Reference",
        "Http": "HTTP",
        "user_management": "User Management",
        "README": "Getting Started"
    }
}

Publish example config:

php artisan vendor:publish --tag=docsites-examples

Alias Feature:

Define custom display names for files and folders
Key must match the exact file/folder name (case-sensitive)
Value is the display name shown in the navigation
Index files (README.md, index.md): Alias takes priority over config name

Name Precedence for Index Files:

JSON alias (if defined in docsites.json)
Config name (from config/docsites.php)
Default "Overview"

Automatic Name Formatting (when not aliased):

snake_case files: user_management.md → "User Management"
camelCase files: myDocument.md → "My Document"
ALL_CAPS preserved: user_API_guide.md → "User API Guide"
Default: Capitalizes first letter

Usage

Basic Documentation Structure

Create documentation groups by creating folders in docs/
Add markdown files with your content
Use nested folders for organized structure
Add index files (README.md or index.md) for folder overviews

Accessing Documentation

Visit http://your-app.test/docs to see your documentation.

File Naming

Files are automatically slugified for URLs
Http Controllers.md → /docs/group/http-controllers
Case-insensitive matching works seamlessly
Index files (README.md, index.md) can be customized

Markdown Features

Full GitHub Flavored Markdown support:

Headers (H1-H6)
Lists (ordered and unordered)
Code blocks with syntax highlighting
Tables
Blockquotes
Links and images
Inline code
Bold and italic text
Horizontal rules

Code Syntax Highlighting

Supported languages include PHP, JavaScript, TypeScript, Bash, JSON, YAML, and many more:

```php
Route::get('/docs', function () {
    return view('welcome');
});
```

Dark/Light Mode

Users can toggle between themes using the button in the top-right corner. Preference is saved in localStorage.

Customization

Theme Colors

Edit resources/css/docsites/markdown.css to customize colors:

.markdown-content {
    color: #1f2937; /* Light mode text */
}

.dark .markdown-content {
    color: #e5e7eb; /* Dark mode text */
}

Custom Middleware

Add authentication or custom middleware in config/docsites.php:

'middleware' => ['web', 'auth', 'verified'],

Custom Route Prefix

Change the route prefix:

'route_prefix' => 'documentation',

Now accessible at /documentation instead of /docs.

Index File Customization

Customize how README.md/index.md files appear:

'index_file' => [
    'name' => 'Getting Started',  // Custom display name
    'sort' => 'append',            // Show at bottom instead of top
],

Production Deployment

Security Recommendations

Restrict environments:
```
'allowed_environments' => ['local'],
```

Add authentication:

'middleware' => ['web', 'auth', 'admin'],

Use environment variables:

'enabled' => env('DOCSITES_ENABLED', false),

Disable in production (if sensitive):
```
DOCSITES_ENABLED=false
```

File Structure

lib/docsites/
├── composer.json
├── config/
│   └── docsites.php
├── resources/
│   ├── css/
│   │   └── markdown.css
│   ├── js/
│   │   └── Pages/
│   │       └── DocSites/
│   │           ├── Index.tsx
│   │           └── Show.tsx
│   └── views/
│       └── app.blade.php
├── routes/
│   └── web.php
└── src/
    ├── DocSitesServiceProvider.php
    ├── Http/
    │   └── Controllers/
    │       ├── DocsController.php
    │       └── DocGroupController.php
    └── Services/
        └── DocScanner.php

Troubleshooting

Routes not working

Check if your environment is allowed:

'allowed_environments' => ['local', 'production'],

Clear route cache:

php artisan route:clear
php artisan route:cache

Styling issues

Make sure CSS is published:

php artisan vendor:publish --tag=docsites-css --force

Rebuild assets:
```
npm run build
```

Markdown not rendering

Check NPM dependencies are installed:

npm install react-markdown remark-gfm rehype-highlight rehype-raw highlight.js

Clear browser cache and rebuild:
```
npm run build
```

Nested routes not working

Make sure your web server supports the wildcard routing. For Nginx:

try_files $uri $uri/ /index.php?$query_string;

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This package is open-sourced software licensed under the MIT license.

Credits

Built with Laravel
UI powered by Tailwind CSS
Markdown rendering with react-markdown
Syntax highlighting by highlight.js
Icons from Lucide

Support

For issues, questions, or suggestions, please open an issue on GitHub.

buzekpdev / laravel-docsites

Maintainers

Details