Getting Started

Installation:

composer require mpociot/documentarian

Publish the configuration and assets:

php artisan vendor:publish --provider="Mpociot\Documentarian\DocumentarianServiceProvider"

Configuration: Update config/documentarian.php to define your API documentation paths:

'paths' => [
    'documentation' => resource_path('docs'),
    'assets' => public_path('docs/assets'),
],

First Use Case: Create a README.md in resource_path('docs') with basic API structure:

# API Documentation

## Introduction
Welcome to our API!

## Endpoints
### GET /users
```json
{
    "users": [...]
}

Run `php artisan documentarian:serve` to preview locally at `http://localhost:8000/docs`.

Implementation Patterns

Markdown-Based Documentation:
- Store API specs in Markdown files (e.g., resource_path('docs/endpoints/users.md')).
- Use YAML frontmatter for metadata (e.g., endpoint paths, HTTP methods):
```
---
endpoint: /users
method: GET
---
# Users Endpoint
Fetch all users.
```

Laravel Route Integration: Add a route in routes/web.php:

Route::get('/docs', function () {
    return Documentarian::render();
});

Asset Management:
- Place static assets (CSS, JS, images) in public_path('docs/assets').
- Override default assets by publishing the package’s assets:
```
php artisan vendor:publish --tag=documentarian-assets
```
Custom Templates: Extend the default theme by copying vendor/mpociot/documentarian/resources/views to resources/views/vendor/documentarian and modifying as needed.

Edit and Preview:
```
php artisan documentarian:serve
```
Auto-reloads changes during development.
Generate Static Files:
```
php artisan documentarian:build
```
Compiles assets and generates static HTML for production.
Versioning: Use subdirectories (e.g., resource_path('docs/v1')) for API versioning and include version-specific routes.

Asset Paths:
- Ensure public_path('docs/assets') is writable. Permissions issues may break asset compilation.
- Clear cached views if assets fail to load:
```
php artisan view:clear
```
Markdown Parsing:
- YAML frontmatter must be valid (use YAML linting tools).
- Avoid special characters in filenames (e.g., users.md works; [email protected] may fail).
Laravel Caching:
- Disable caching during development if changes aren’t reflecting:
```
// config/documentarian.php
'cache' => env('APP_ENV') !== 'local',
```
Route Conflicts:
- Ensure /docs doesn’t conflict with existing routes. Use middleware to restrict access:
```
Route::get('/docs', function () {
    return Documentarian::render();
})->middleware('auth');
```

Check Logs: Run with verbose output:

php artisan documentarian:serve --verbose

Validate Markdown: Use a Markdown linter (e.g., Markdown Lint) to catch syntax errors.

Frontmatter Validation: Test YAML frontmatter with:

composer require --dev symfony/yaml

Then validate in PHP:

use Symfony\Component\Yaml\Yaml;
$yaml = Yaml::parse(file_get_contents('path/to/file.md'));

Custom Renderers: Extend Mpociot\Documentarian\Renderers\RendererInterface to support additional formats (e.g., JSON schemas).

Hooks: Override the DocumentarianServiceProvider to add middleware or filters:

public function boot()
{
    Documentarian::extend(function ($renderer) {
        // Modify renderer behavior
    });
}

API Blueprints: Integrate with tools like API Blueprint by converting blueprints to Markdown before processing.

CI/CD Integration: Automate builds in GitHub Actions:

- name: Build Documentation
  run: php artisan documentarian:build

Search Functionality: Use Lunr.js for client-side search by including it in resources/views/vendor/documentarian/layouts/master.blade.php.
Dark Mode: Add a CSS toggle for dark/light themes by extending the default stylesheet.