Getting Started

Minimal Setup

Installation:
```
composer require binarytorch/larecipe
php artisan larecipe:install
```
This publishes the config, assets, and creates a resources/docs directory (default location for Markdown files).
First Use Case: Create a Markdown file in resources/docs/ (e.g., resources/docs/getting-started.md) with basic content:
```
# Getting Started
Welcome to your Laravel app's documentation!
```
Access it at /docs/getting-started. LaRecipe automatically renders the file with syntax highlighting, tables of contents, and theming.
Key Configuration: Check config/larecipe.php for:
- docs_path: Override the default resources/docs location.
- theme: Switch between default, dark, or custom themes (e.g., binarytorch/larecipe-dark-theme).
- middleware: Add auth (e.g., web) or custom middleware to restrict access.
- search: Enable Algolia or simple local search.
Route Registration: LaRecipe registers /docs as a route by default. Customize it in routes/web.php if needed:
```
Route::prefix('docs')->group(function () {
    \Binarytorch\LaRecipe\LaRecipe::routes();
});
```

Publish Assets: If you modified the Vue/JS assets (e.g., for theming), run:

php artisan vendor:publish --tag=larecipe-assets
npm run dev  # or npm run build

Implementation Patterns

1. Markdown Workflows

File Structure: Organize docs in a hierarchy (e.g., resources/docs/api/, resources/docs/guides/). LaRecipe auto-generates a sidebar navigation based on subdirectories. Example:
```
resources/docs/
├── api/
│   ├── auth.md
│   └── users.md
└── guides/
    └── deployment.md
```
Frontmatter: Use YAML frontmatter in Markdown files to customize metadata:
```
---
title: "API Authentication"
description: "How to authenticate with the API"
order: 1
hidden: false
---
```
- order: Controls sidebar sorting.
- hidden: Excludes from navigation.
- icon: Customize sidebar icons (e.g., icon: "fas fa-user-shield").
Includes: Reuse snippets across docs with {% include %}:
```
{% include 'partials/_api-response.md' %}
```

2. API Documentation

Route Annotations: Annotate Laravel routes in routes/api.php or controllers to auto-generate API docs:

Route::get('/users', [UserController::class, 'index'])
     ->middleware('auth:sanctum')
     ->recipe([
         'description' => 'List all users',
         'tags' => ['users'],
         'auth' => ['sanctum'],
         'responses' => [
             200 => ['description' => 'Successful response', 'schema' => UserResource::class],
         ],
     ]);

LaRecipe renders this as a Swagger-like UI with:

Endpoint descriptions.
Auth requirements.
Response schemas (if using Laravel’s Resource classes).

Controller Methods: Annotate controller methods similarly:

/**
 * @recipe([
 *     "description" => "Retrieve a user by ID",
 *     "parameters" => [
 *         ["name" => "id", "in" => "path", "required" => true, "schema" => ["type" => "integer"]],
 *     ],
 *     "responses" => [
 *         200 => ["description" => "User details"],
 *     ]
 * ])
 */
public function show(User $user) { ... }

3. Theming and Extensions

Custom Themes: Extend the default theme by publishing assets and overriding Vue components:
```
php artisan vendor:publish --tag=larecipe-assets
```
Modify resources/js/components/ to customize:
- Sidebar (Sidebar.vue).
- Header (Header.vue).
- Documentation layout (DocLayout.vue).

Dark Mode: Install the official dark theme:

composer require binarytorch/larecipe-dark-theme

Enable it in config/larecipe.php:

'theme' => \Binarytorch\LaRecipe\Themes\DarkTheme::class,

RTL Support: For Arabic/Hebrew docs, install:

composer require binarytorch/larecipe-rtl

Set in config:

'rtl' => true,

4. Search Integration

Algolia: Configure in config/larecipe.php:

'search' => [
    'driver' => 'algolia',
    'app_id' => env('ALGOLIA_APP_ID'),
    'api_key' => env('ALGOLIA_API_KEY'),
    'index_name' => env('ALGOLIA_INDEX_NAME'),
],

Run the indexer:

php artisan larecipe:search:index

Local Search: Enable the built-in search:

'search' => [
    'driver' => 'local',
],

5. Authentication and Access Control

Middleware: Restrict docs to authenticated users:

'middleware' => ['auth'],

Or use custom middleware:

'middleware' => [\App\Http\Middleware\DocsAccess::class],

Role-Based Access: Use Laravel’s gates/policies to control doc visibility:

// In a service provider
Gate::define('view-docs', function ($user) {
    return $user->hasRole(['admin', 'developer']);
});

Then add to config/larecipe.php:

'authorization' => [
    'guard' => 'web',
    'policy' => \App\Policies\DocsPolicy::class,
],

6. CI/CD Integration

Git Hooks: Add a pre-commit hook to validate Markdown syntax:

npm install --save-dev markdownlint-cli

Create .github/markdownlint.json:

{
    "default": true,
    "MD013": false // Allow single-line lists
}

Add to package.json:

"scripts": {
    "lint:docs": "markdownlint 'resources/docs/**/*.md'"
}

Deployment: Ensure docs are built in your CI pipeline (if using custom themes):

# .github/workflows/deploy.yml
jobs:
  deploy:
    steps:
      - run: npm run build
      - run: php artisan larecipe:search:index --force

7. Feedback and Analytics

Feedback Widget: Install the feedback package:

composer require binarytorch/larecipe-feedback

Enable in config:

'feedback' => true,

Google Analytics: Add to resources/js/app.js:

window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'YOUR_TRACKING_ID');

Gotchas and Tips

Pitfalls

Markdown Parsing Quirks:
- Tables: Ensure proper alignment in Markdown tables (LaRecipe uses marked.js under the hood). Example:
```
| Left-Aligned | Center-Aligned | Right-Aligned |
|:-------------|:--------------:|--------------:|
| Left         | Center         | Right         |
```
- Code Blocks: Use triple backticks for syntax highlighting:
```
```php
  Route::get('/users', function () {
      return User::all();
  });
```
- Nested Headers: Avoid excessive nesting (e.g., ######); LaRecipe’s TOC may truncate deeply nested content.

Route Conflicts:

If /docs conflicts with existing routes, override the route in routes/web.php:

Route::get('/internal-docs', [\Binarytorch\LaRecipe\LaRecipe::class, 'serve'])->name('docs');

Then update the config:

'route' => 'docs',

Asset Compilation:
- After publishing assets, always run npm run dev or npm run build to avoid stale Vue/JS bundles.

Larecipe Laravel Package