Kirby 3 - Static Site Generator
With this plugin you can create a directory with assets, media and static html files generated from your pages. You can simply upload the generated files to any CDN and everything (with small exceptions, see below) will still work. The result is an even faster site with less potential vulnerabilities.
What is Kirby?
Kirby is a highly customizable and file-based CMS (content management system). Before using this plugin make sure you have installed the latest version of Kirby CMS and are familiar with the plugin basics.
How to install the plugin
If you use composer, you can install the plugin with:
composer require d4l/kirby-static-site-generator
Alternatively, create a
static-site-generator folder in
site/plugins, download this repository and extract its contents into the new folder.
- Compatibility with multilanguage sites
- Translated URLs
- Media (also when resized; files are automatically generated and copied when used)
- Customizable base URL
- Customizable paths to copy
- Customizable output folder
- Preserve individual files / folders in the output folder
What doesn't work
- Custom routes
- Directly opening the html files in the browser with the file protocol (absolute base url
How to use it
1) Directly (e.g. from a kirby hook)
$staticSiteGenerator = new D4L\StaticSiteGenerator($kirby, $pathsToCopy = null, $pages = null); $fileList = $staticSiteGenerator->generate($outputFolder = './static', $baseUrl = '/', $preserve = );
$pathsToCopy: if not given,
$kirby->roots()->assets()is used; set to
to skip copying other files than media
$pages: if not given, all pages are rendered
$preserveto preserve individual files or folders in your output folder, e.g. if you want to preserve a
README.mdin your output folder, set
['README.md']; any files or folders directly in the root level and starting with
.are always preserved (e.g.
2) By triggering an endpoint
To use this, adapt config option
d4l.static_site_generator.endpoint to your needs (should be a string)
3) By using a
Do the same as for option 2) and then add a
staticSiteGenerator type field to one of your blueprints:
fields: staticSiteGenerator: label: Generate a static version of the site # ... (see "Field options")
Available configuration options
return [ 'd4l' => [ 'static_site_generator' => [ 'endpoint' => null, # set to any string like 'generate-static-site' to use the built-in endpoint (necessary when using the blueprint field) 'output_folder' => './static', # you can specify an absolute or relative path 'preserve' => , # preserve individual files / folders in the root level of the output folder (anything starting with "." is always preserved) 'base_url' => '/', # if the static site is not mounted to the root folder of your domain, change accordingly here 'skip_media' => false, # set to true to skip copying media files, e.g. when they are already on a CDN; combinable with 'preserve' => ['media'] 'skip_templates' =>  # ignore pages with given templates (home is always rendered) ] ] ];
All of these options are only relevant if you use implementation options 2) or 3).
When directly using the
D4L\StaticSiteGenerator class, no config options are required.
In that case, options like
skip_media can be achieved by calling
label: Generate static site help: Custom help text progress: Custom please-wait message success: Custom success message error: Custom error message
Be careful when specifying the output folder, as the given path (except files starting with
.) will be erased before the generation! There is a safety check in place to avoid accidental erasure when specifying existing, non-empty folders.
Feedback and contributions are welcome!
For commit messages we're following the gitmoji guide
Please post all bug reports in our issue tracker. We have prepared a template which will make it easier to describe the bug.