Keeping your documentation in sync with your codebase is crucial for maintainability and developer experience. The Laradocs package offers a streamlined solution by allowing you to manage your documentation directly within your Laravel application's files.
Laradocs transforms Markdown files, stored alongside your code, into a fully functional documentation website accessible at a designated route, typically /docs. This approach ensures that your documentation evolves with your application, benefiting from version control and simplifying the development workflow.
Key Features
Laradocs boasts a range of features designed to enhance documentation management:
- Hierarchical Navigation: Multi-level folder structures are automatically translated into nested navigation menus, making it easy for users to browse through documentation sections.
- Flexible Routing: Content routing can be based on filenames or overridden using front-matter metadata, providing control over URL structures.
- Markdown Processing: Leverages CommonMark for rendering Markdown, supporting GitHub-Flavored Markdown, tables, and footnotes.
- Rich Metadata: Each documentation page can include extensive front-matter metadata such as title, description, order, group, badges, redirects, tags, and slugs.
- Polished UI: Offers a responsive user interface with features like dark mode, a sidebar, breadcrumbs, an on-page table of contents, and previous/next navigation. The UI is publishable and customizable.
- Efficient Caching: Implements smart caching for rendered HTML, with automatic invalidation triggered by file changes.
Structuring Your Docs
The directory structure of your documentation files directly influences the sidebar navigation. Nested folders create distinct sections, and an _index.md file serves as the landing page for each section. For instance, you can scaffold a new documentation page using the Artisan command:
php artisan make:doc guide/getting-started --title="Getting Started" --order=1
Front-Matter for Control
YAML front-matter within your Markdown files allows for granular control over how each page is presented and organized. Fields like title, description, order, group, hidden, badge, redirect, tags, and slug can be defined:
---
title: Getting Started
description: Install and configure the app.
order: 1
group: Basics
---
Laradocs also supports callout blocks using familiar GitHub syntax for enhanced readability:
> [!TIP]
> Folders become sidebar sections; `_index.md` is a section's landing page.
Reusability with Variables and Macros
To promote consistency and reduce repetition, Laradocs enables the definition of shared variables and reusable macro blocks within a service provider. Variables can be interpolated using {{ value }} syntax, while macros are invoked via @docs() blocks.
use PeteBishwhip\Laradocs\Facades\Laradocs;
Laradocs::variables(fn () => ['version' => '1.0.0']);
Laradocs::share('app_name', config('app.name'));
Laradocs::macro('tweet', fn (array $args) => "<a href=\"...\">@{$args['user']}</a>");
SEO, Caching, and Output Management
Laradocs automatically generates essential SEO elements, including meta tags, Open Graph and Twitter card data, and JSON-LD. A sitemap is also generated at {prefix}/sitemap.xml. The package intelligently caches rendered pages and invalidates them upon detecting changes in source files. Manual cache management is available through Artisan commands:
php artisan laradocs:cache
php artisan laradocs:clear
This package requires PHP 8.2+ and is compatible with Laravel 11, 12, and 13. For more details, visit the Laradocs website or explore the source code on GitHub.
