Docify Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require techenby/docify
   php artisan docify:install
   

   This creates a docs/ directory in your project root with a default index.md file.

2. First Use Case:

   • Access /docs in your Laravel app (only in local environment by default).
   • Edit docs/index.md to add your own Markdown content.
   • Refresh the /docs page to see your changes rendered.

Where to Look First

• Default Docs Location: docs/ folder in your project root.
• Configuration: Published via php artisan vendor:publish (config, Livewire component, and layout).
• Environment Restrictions: Check config/docify.php for allowed environments.

Implementation Patterns

Core Workflows

1. Documentation Management:

   • Store all Markdown files in the docs/ directory.
   • Use nested folders for hierarchical documentation (e.g., docs/api/endpoints.md).
   • Reference files with relative paths (e.g., [API Endpoints](./api/endpoints.md)).

2. Livewire Integration:

   • The package provides a Livewire component (Docify) for rendering docs.
   • Customize the layout by publishing the view:

     php artisan vendor:publish --tag=docify-layout
     

   • Extend the component by copying and modifying resources/views/vendor/docify.blade.php.

3. Environment-Specific Access:

   • Restrict access to specific environments (e.g., local, staging) via config/docify.php:

     'environments' => ['local', 'staging'],
     

4. Editor Integration:

   • Set the default editor for the "Edit" link via .env:

     DOCIFY_EDITOR=cursor  # or 'vscode', 'phpstorm', etc.
     

   • Falls back to DEBUGBAR_EDITOR or IGNITION_EDITOR if DOCIFY_EDITOR is unset.

5. Theming:

   • Override the default styling by publishing the CSS:

     php artisan vendor:publish --tag=docify-css
     

   • Customize the resources/css/docify.css file.

Integration Tips

• Route Guarding: Add middleware to protect the /docs route in production:

  Route::middleware(['web', 'auth'])->get('/docs', [Docify::class, 'index']);
  

• API Documentation: Use the docs/ folder to document API endpoints. Example structure:

  docs/
  ├── api/
  │   ├── endpoints.md
  │   └── models.md
  └── index.md
  

• CI/CD Pipelines: Exclude the docs/ folder from Git if it’s auto-generated (e.g., via php artisan docify:install in CI). Use .gitignore:

  /docs/
  

• Local Development: Use the "Edit" link to open Markdown files in your preferred editor (e.g., VS Code, Cursor). Requires DOCIFY_EDITOR to be set.

Gotchas and Tips

Pitfalls

1. Environment Restrictions:

   • By default, /docs is only accessible in the local environment. Forgetting to update config/docify.php can lock you out of the docs in other environments (e.g., staging).
   • Fix: Always publish the config and update the environments array:

     'environments' => ['local', 'staging', 'production'], // Example for broader access
     

2. Editor Link Failures:

   • The "Edit" link relies on DOCIFY_EDITOR, DEBUGBAR_EDITOR, or IGNITION_EDITOR being set. If none are configured, the link will break.
   • Fix: Set DOCIFY_EDITOR in .env:

     DOCIFY_EDITOR=vscode
     

   • Fallback: Manually open the docs/ folder in your editor if the link fails.

3. Markdown Rendering Quirks:

   • Docify uses a basic Markdown parser. Complex syntax (e.g., tables, advanced syntax highlighting) may not render perfectly.
   • Tip: Test Markdown in docs/index.md before relying on it for critical documentation.

4. Livewire Component Caching:

   • Changes to the Livewire component or layout may not reflect immediately due to Laravel’s view caching.
   • Fix: Clear the view cache:

     php artisan view:clear
     

5. File Permissions:

   • The php artisan docify:install command creates the docs/ folder with default permissions. If your web server (e.g., Nginx, Apache) lacks write access, you may encounter issues when editing files via the "Edit" link.
   • Fix: Ensure the docs/ folder is writable:

     chmod -R 755 docs/
     

Debugging Tips

1. Check the Config:

   • Verify config/docify.php for correct settings, especially environments and editor.
   • Run php artisan config:clear if changes aren’t applying.

2. Livewire Logs:

   • Enable Livewire logging to debug component issues:

     'log' => env('APP_DEBUG', false),
     

     in config/livewire.php.

3. Markdown Parsing:

   • If Markdown isn’t rendering, check for syntax errors in your .md files. Use a tool like Markdown Live Preview to validate.

4. Route Debugging:

   • Ensure the /docs route is registered. Run:

     php artisan route:list
     

     to verify the route exists.

Extension Points

1. Custom Layouts:

   • Override the default layout by publishing and modifying resources/views/vendor/docify.blade.php.
   • Example: Add a header, footer, or sidebar navigation.

2. Custom Markdown Processing:

   • Extend the Markdown parser by creating a custom service provider. Bind a new parser to the docify.markdown tag:

     $this->app->bind('docify.markdown', function () {
         return new CustomMarkdownParser();
     });
     

3. Dynamic Documentation:

   • Fetch documentation from an external source (e.g., API) by extending the Docify Livewire component. Override the getDocs() method to return custom content.

4. Search Functionality:

   • Add a search bar by extending the layout. Use a library like Lunr.js for client-side search.

5. Versioning:

   • Implement documentation versioning by storing docs in docs/v1/, docs/v2/, etc., and adding a version selector to the layout. Use route parameters to switch versions:

     Route::get('/docs/{version?}', [Docify::class, 'index'])->where('version', 'v[0-9]+');