README

A beautiful Laravel package for viewing Markdown documentation with GitHub-style rendering, search functionality, and zero configuration.

✨ Features

📖 Beautiful GitHub-Style Rendering - Professional documentation view
🔍 Real-time Search - Find docs instantly with Ctrl+K
🎨 Syntax Highlighting - Code blocks with Highlight.js
📱 Responsive Design - Works on all devices
🔒 Secure - Protection against directory traversal
📋 Copy Code Buttons - One-click code copying
⚡ Zero Configuration - Works out of the box
🗂️ Folder Organization - Automatic categorization
🎯 SEO Friendly - Proper heading structure

📋 Requirements

PHP 8.1 or higher
Laravel 10.x or ^11.x
Composer

🚀 Installation

Install the package via Composer:

composer require smmahfujurrahman/docgen

The package will automatically register its service provider.

📦 Publishing Assets

Publish all assets at once:

php artisan vendor:publish --tag=docgen

Or publish specific assets:

# Publish configuration
php artisan vendor:publish --tag=docgen-config

# Publish routes
php artisan vendor:publish --tag=docgen-routes

# Publish views
php artisan vendor:publish --tag=docgen-views

# Publish dummy documentation
php artisan vendor:publish --tag=docgen-docs

🎯 Usage

Quick Start

Install the package (see above)
Publish the assets:
```
php artisan vendor:publish --tag=docgen
```
Access your documentation:
```
http://your-app.test/documentation
```

That's it! You'll see the welcome page with dummy documentation.

Adding Your Documentation

Navigate to the docs folder in your Laravel project root
Add your .md (Markdown) files
Refresh the documentation page

Example structure:

docs/
├── README.md
├── installation.md
├── api/
│   ├── authentication.md
│   └── endpoints.md
└── guides/
    ├── getting-started.md
    └── deployment.md

Linking Routes in Your App

After publishing, update your routes/web.php to include the documentation routes:

// At the end of routes/web.php
if (file_exists(base_path('routes/docs.php'))) {
    require base_path('routes/docs.php');
}

Or if you want to customize, you can manually define routes using the config:

Route::get('/docs', function () {
    // Your custom implementation
});

⚙️ Configuration

The configuration file will be published to config/docgen.php:

return [
    // Route prefix for documentation (default: 'documentation')
    'route_prefix' => env('DOCGEN_ROUTE_PREFIX', 'documentation'),
    
    // Directory where markdown files are stored (default: 'docs')
    'docs_path' => env('DOCGEN_DOCS_PATH', 'docs'),
    
    // Auto-register routes (default: true)
    'auto_register_routes' => env('DOCGEN_AUTO_ROUTES', true),
    
    // CommonMark configuration
    'commonmark' => [
        'html_input' => 'allow',
        'allow_unsafe_links' => false,
    ],
];

Environment Variables

Add these to your .env file to customize:

DOCGEN_ROUTE_PREFIX=documentation
DOCGEN_DOCS_PATH=docs
DOCGEN_AUTO_ROUTES=true

🎨 Customization

Customizing Views

Publish the views and modify them:

php artisan vendor:publish --tag=docgen-views

Views will be copied to resources/views/documentations/:

docs-index.blade.php - Documentation index page
docs-viewer.blade.php - Individual document viewer

Customizing Styles

Edit the published views to change colors, fonts, or layout. The views use inline CSS for easy customization.

Custom Routes

If you want full control over routes, set auto_register_routes to false in config and define your own routes:

use League\CommonMark\CommonMarkConverter;

Route::get('/my-docs', function () {
    // Your custom documentation logic
});

🔒 Security Features

DocGen includes built-in security:

File Type Validation: Only .md files are accessible
Directory Traversal Protection: Prevents ../ attacks
Path Validation: Uses realpath() for secure path resolution
Configurable Paths: Restrict docs to specific directories

📖 Markdown Support

DocGen supports full Markdown syntax:

Basic Formatting

# Heading 1
## Heading 2
### Heading 3

**Bold Text**
*Italic Text*
~~Strikethrough~~

[Link](https://example.com)
![Image](image.jpg)

Code Blocks

```php
<?php
echo "Hello, World!";


### Tables

```markdown
| Column 1 | Column 2 |
|----------|----------|
| Data 1   | Data 2   |

Lists

- Unordered item
- Another item

1. Ordered item
2. Another item

Blockquotes

> This is a blockquote

🎯 Features in Detail

Search Functionality

Real-time search as you type
Searches both filenames and content titles
Keyboard shortcut: Ctrl+K (Windows/Linux) or Cmd+K (Mac)
Press Escape to clear search

Syntax Highlighting

PHP, JavaScript, Python, Ruby, Java, C++, and more
Auto-detection of languages
GitHub color scheme

Copy Code Buttons

Appears on hover over code blocks
One-click copying to clipboard
Visual feedback on successful copy

Responsive Design

Mobile-first approach
Tablet-optimized layouts
Desktop full-feature experience

🛠️ Development

Local Package Development

To test the package locally before publishing:

Add to your Laravel app's composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "./packages/smmahfujurrahman/docgen"
        }
    ]
}

Require the package:

composer require smmahfujurrahman/docgen:@dev

Running Tests

composer test

📝 Changelog

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

🤝 Contributing

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

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

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

👤 Author

S. M. Mahfujur Rahman

GitHub: @MahfujuRahman
Email: mahfujur.dev@gmail.com

🙏 Credits

Built with Laravel
Markdown parsing by CommonMark
Syntax highlighting by Highlight.js
Icons by Font Awesome
Styling inspired by GitHub

💡 Support

If you find this package helpful, please consider:

⭐ Starring the repository
🐛 Reporting bugs
💡 Suggesting new features
📝 Improving documentation

Made with ❤️ by S. M. Mahfujur Rahman

smmahfujurrahman / docgen

Maintainers

Details