Laravel Static Documentation Sites, Blazingly Fast and Stupidly Simple

Latest Version on Packagist Total Downloads License GitHub Actions GitHub Actions

Now with Dark Mode Support!

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:

1composer require desilva/laradocgen --dev

Publish the assets

1php artisan vendor:publish --tag="laradocgen"

Build the static site

1php 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.

1❌ "kebab case title.markdown" # Returns 404
2✔️ "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/

1![My Image](media/image.png "Image Title") # Note the relative path

Build the static site

1php 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

1php 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

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 [email protected] 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

Packages used and special mentions

More Badges

Latest Version on Packagist Latest Version on Packagist (including pre-releases) GitHub Actions