options.md

Kirby StaticBuilder options

StaticBuilder offers a handful of options so that you can tweak the result, depending on your taste or your technical requirements. Need to export a documentation that can be shared as a folder of files (rather than hosted on a web server)? That’s doable. Only export part of a website? Sure.

Option defaults

c::set([
    'staticbuilder'            => false,
    'staticbuilder.outputdir'  => 'static',
    'staticbuilder.assets'     => ['assets', 'content', 'thumbs'],
    'staticbuilder.baseurl'    => '/',
    'staticbuilder.uglyurls'   => false,
    'staticbuilder.extension'  => '/index.html',
    'staticbuilder.filter'     => null,
    'staticbuilder.withfiles'  => false
]);

Common scenarios

Hosting on a domain or subdomain

With default settings you should be able to put the contents of the static folder directly on your website’s root.

• Page files will look like: my/page.html
• URLs will look like: /my/page

Make sure that your server config allows serving my/page.html when requesting the /my/page URL.

With Apache, this requires the Multiviews options, which you can probably enable in an .htaccess file if needed:

Options +Multiviews

Copying page files

There are several options for copying page files and making sure that your links and file references still work.

1. Copy the thumbs folder. By default the thumbs folder will be copied, and if all images you’re using in your pages go through the thumb() helper or $image->thumb() method, you’re golden.

2. Copy the content folder and use Kirby tags. By default the content folder will be copied as well, so that links to content/1-section/3-page/myfile.pdf etc. keep working. If you used Kirby tags to embed images and link to page files, you don’t have anything else to do.

3. Tell StaticBuilder to copy page files to a folder named after the page: e.g. section/page/myfile.pdf.

The last option will work for relative paths in your HTML (<a href="myfile.pdf">My File</a> or <img src="hello.svg" alt="">) only if the page HTML is written to the same folder. So you probably want to use the extension and withfiles options together:

c::set([
    'staticbuilder'            => true,
    'staticbuilder.extension'  => '/index.html',
    'staticbuilder.withfiles' => true
]);

HTML pages outside of a web site

If you need to share the resulting site outside of a web server (on a local network share for documentation, on a thumb drive, distributed as a ZIP file, etc.), you will need fully relative URLs between pages.

This can be achieved with this configuration:

c::set([
    'staticbuilder'          => true,
    'staticbuilder.baseurl'  => './',
    'staticbuilder.uglyurls' => true
]);

In the output, URLs from page A to page B should look like: ./../other-section/page-b.html.

Note that this plugin only rewrites URLs that are generated by Kirby objects or by the url() helper function. If you hardcoded some URLs or paths in your templates, they won’t be rewritten.

Option details

staticbuilder.outputdir

By default, the static site will be generated in [yourproject]/static. You can change this path, providing a relative path (e.g. ../build/static) or an absolute one (e.g. /Users/me/Sites/mywebsite/static).

Two restrictions:

1. PHP and your local web server (Apache/MAMP/WAMP/etc.) must permissions to write to that folder.
2. The output folder MUST be named static, even if you change the path. This restriction helps making sure you don’t kill your system or delete existing files.

WARNING: when building the site, the contents of this folder will be deleted first. You should not change the contents of this folder manually, or you will lose your changes on the next build!

staticbuilder.assets

A list of static files or folders to copy in the static directory.

c::set('staticbuilder.assets', [
    // Copy the full 'assets' folder
    'assets',
    // Thumbs too
    'thumbs',
    // Use key=>value syntax to change the destination
    'assets/images/favicon.ico' => 'favicon.ico',
    // Getting a file from outside the main project dir
    '../server/static-htaccess.conf' => '.htaccess'
]);

Note: * or other wildcards are not supported. You need explicit paths to existing files or folders.

staticbuilder.baseurl

This overrides Kirby’s default 'url' option.

// Works well for hosting on a domain or subdomain
c::set('staticbuilder.baseurl', '/');

// If hosting in a subfolder
c::set('staticbuilder.baseurl', '/something');

// You can provide a full URL if you want, but that will
// probably make it harder to test the result locally
c::set('staticbuilder.baseurl', 'http://mysite.com');

Finally, there is a magic value for relative URLs:

// Change all URLs to fully relative
c::set('staticbuilder.baseurl', './');

Then URLs from page A to page B should look like ./../../other-section/page-b.

WARNING: relative URLs are only computed for URLs generated by Kirby, using the $page->url(), $file->url(), $thumb->url() etc. methods, or the url('some/path') method. If you have hardcoded URLs in your templates or in your content, they will not be modified!

staticbuilder.uglyurls

Should we include the full filename in page URLs or not? (Defaults to false.)

// Page URL might look like:
//   /my/page
c::set('staticbuilder.uglyurls', false);

// Page URL might look like:
//   /my/page.html (default)
//   /my/page/index.html (custom extension config)
c::set('staticbuilder.uglyurls', true);

staticbuilder.extension

Extension for pages. Defaults to adding a /index.html suffix.

c::set('staticbuilder.extension', '/index.html'); // my/page/index.html
c::set('staticbuilder.extension', '.html');       // my/page.html

staticbuilder.filter

With this option you can provide a PHP callback that gets each Page object as its only parameter, and which should return true for pages to build and false for pages to exclude.

Optionally, this callback can return an array with a boolean value and a message explaining why a page was filtered in or out.

This example filters out pages that do not match the specified template names:

c::set('staticbuilder.filter', function($page){
    $template = $page->intendedTemplate();
    $allowed = ['page', 'post', 'blog', 'error', 'home'];
    if (in_array($template, $allowed)) {
        return true;
    } else {
        return [false, "Template '$template' excluded from static build"];
    }
});

The default filter excludes folders that don’t have a text file, and folders that only contain Kirby Modules. You can reuse this default filter in your code:

c::set('staticbuilder.filter', function($page) {
    // Check our custom logic for articles
    if ($page->intendedTemplate() == 'article' && !$page->isPublished()) {
        return [false, 'Unpublished articles are excluded from static build'];
    }
    // And fall back to the default logic for other pages
    return Kirby\StaticBuilder\Builder::defaultFilter($page);
});

staticbuilder.withfiles

Should we copy page files in their parent’s target directory? (Defaults to false.)

// Copy a page’s files (images, documents etc.), e.g.
// content/1-my/3-page/image.jpg -> static/my/page/image.jpg
// content/1-my/3-page/doc.pdf   -> static/my/page/doc.pdf
c::set('staticbuilder.withfiles', true);

Note that for multilingual sites this would copy the files for each language (if you have 3 languages, each file gets copied to 3 different locations).

You can also specify a filter function to specify which files should get copied over:

c::set('staticbuilder.withfiles', function($file) {
    // Only copy page files smaller than 250kB
    return $file->size() < 256000;
});

We’re using Kirby’s $files->filter() method. See also the available file methods.