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:

1. JSON alias (if defined in docsites.json)
2. Config name (from config/docsites.php)
3. 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

1. Create documentation groups by creating folders in docs/
2. Add markdown files with your content
3. Use nested folders for organized structure
4. 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

1. Restrict environments:

   'allowed_environments' => ['local'],

2. Add authentication:

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

3. Use environment variables:

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

4. 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

1. Check if your environment is allowed:

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

2. Clear route cache:

   php artisan route:clear
   php artisan route:cache

Styling issues

1. Make sure CSS is published:

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

2. Rebuild assets:

   npm run build

Markdown not rendering

1. Check NPM dependencies are installed:

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

2. 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.