desilva / laradocgen
Generates static HTML documentation for Laravel based on Markdown with a realtime preview.
Fund package maintenance!
www.buymeacoffee.com/caen
Requires
- php: ^8.0.2
- ext-curl: *
- ext-fileinfo: *
- illuminate/support: ^8.42|^9.0
- league/commonmark: ^2.2
- torchlight/torchlight-commonmark: ^0.5.5
- torchlight/torchlight-laravel: ^0.5.11
Requires (Dev)
- orchestra/testbench: ^6.0
- phpunit/phpunit: ^9.5
Suggests
- laravel/framework: This package has so far only been tested with Laravel 9.2. Please contribute with more tests!
This package is auto-updated.
Last update: 2024-04-30 00:33:43 UTC
README
Now with Dark Mode Support!
Not activly maintained
This project is currently not receiving new features as I am focusing on HydePHP, however, the project will continue to get security fixes indefinitely. Open source contributions are welcome!
Alternatives
This project is a hybrid static site generator and live server package. I have created two other packages that I think are much better suited than this one.
If you want static documentation sites, try out HydePHP which features a significantly faster rendering engine, and is much more refined and easy to get started with.
If you want documentation sites for a Laravel project, try Lagrafo, which started out as Laradocgen v2.0.
About
Hey! I'm Caen! I created this package to practice package development. It is still very much in beta, but please do send me any feedback you have! I'd love to get some PRs as well.
Full Documentation
Full documentation is available at https://docs.desilva.se/laradocgen/. Generated using this package of course!
Alpha Stage Software
Hey! Just a quick heads up that this is a very new package and I expect there to be bugs. If anything goes wrong, do let me know and I'd love to get feedback and PRs!
**Disclaimer** This package is still in the alpha stage. Once it becomes stable and tested enough I will release v1.0 and I will adhere to semantic versioning. But until then I will run canary builds and I am sure there will be breaking changes. I will of course do my best to document them all in the upgrade guides, but all in all, at this stage I would not recommend it for production use. Though since it is intended to run on your local server I don't think much can go wrong as long as you have backups and Git. The only area that is really of concern to me is that since we are working with writing files to disk if something goes wrong files could be overwritten, but as it is now the paths are hardcoded to "safe" directories so it should only be able to overwrite files already created by the package.Installation
The package has so far only been tested with Laravel 9
You can install the package via composer:
composer require desilva/laradocgen --dev
Publish the assets
php artisan vendor:publish --tag="laradocgen"
Build the static site
php artisan laradocgen:build
Your static site will be saved in public/docs
Usage
Adding pages
Pages are generated from markdown files stored in resources/docs/.
Markdown filenames are sanitized through Str::slug(). To prevent 404 errors the filenames must be compatible. In essence, they must be in lowercase kebab-case and end in .md and must not contain spaces.
❌ "kebab case title.markdown" # Returns 404 ✔️ "kebab-case-title.md" # creates my-page-title.html and renders as "My Page Title" in the frontend
And store your images in resources/docs/media/
 # Note the relative path
Build the static site
php artisan laradocgen:build
Your static site will be saved in public/docs
Customization
The package strives to follow Convention over configuration. Everything is preconfigured so you can get started quickly. However, if you wish you can customize the package.
You can publish the Blade views using
php artisan publish --tag="laradocgen-views"
And customize them to your liking. Note that you will need to re-publish the views when updating!
You can customize the source and output directory in the config file. You can use this to create multiple documentation versions.
Package Development
Please see CONTRIBUTING for details.
Changelog
Please see CHANGELOG for more information on what has changed recently.
Contributing
Please see CONTRIBUTING for details.
Roadmap
- Allow the specification of source/build directories. This can also be used for versioning.
- Document Blade view customization
- Add (automatic) versioning support
- Allow the package to run standalone from Laravel
- Add Search feature
- Add Artisan command to create a new Markdown file based on an input title
- Add CLI options to the Artisan build command to override config settings on a per-build basis
Right now there are not very many customization options as I wanted to keep things dead simple. If you have a configuration idea please do make a PR or open a GitHub Issue as I want to allow for more customization down the line.
Security
If you discover any security-related issues, please email caen@desilva.se instead of using the issue tracker. All vulnerabilities will be promptly addressed.
Credits
License
The MIT License (MIT). Please see License File for more information.
Attributions
Please see the respective authors' repositories for their license files
Laravel Package Boilerplate
This package's scaffolding was generated using the Laravel Package Boilerplate.
Frontend
- The frontend is based on the Tailwind Starter Kit from Creative Tim (MIT)
- The dark-mode switch is based on a component from Flowbite (MIT)
Packages used and special mentions
- The frontend is built with TailwindCSS
- Syntax highlighting by Torchlight
- Markdown is parsed with League/Commonmark
- The default favicon was created using Favicon.io using the "Page" Emoji from the amazing open-source project Twemoji. The graphics are copyright 2020 Twitter, Inc and other contributors and are licensed under CC-BY 4.0.
More Badges
