Configuration

Bunto allows you to concoct your sites in any way you can dream up, and it’s
thanks to the powerful and flexible configuration options that this is possible.
These options can either be specified in a _config.yml file placed in your
site’s root directory, or can be specified as flags for the bunto executable
in the terminal.

Configuration Settings

Global Configuration

The table below lists the available settings for Bunto, and the various options (specified in the configuration file) and flags (specified on the command-line) that control them.

Exclude directories and/or files from the
conversion. These exclusions are relative to the site's
source directory and cannot be outside the source directory.

exclude: [DIR, FILE, ...]

Include

Force inclusion of directories and/or files in the conversion.
.htaccess is a good example since dotfiles are excluded
by default.

include: [DIR, FILE, ...]

Keep files

When clobbering the site destination, keep the selected files.
Useful for files that are not generated by bunto; e.g. files or
assets that are generated by your build tool.
The paths are relative to the destination.

keep_files: [DIR, FILE, ...]

Time Zone

Set the time zone for site generation. This sets the TZ
environment variable, which Ruby uses to handle time and date
creation and manipulation. Any entry from the
IANA Time Zone
Database is valid, e.g. America/New_York. A list of all
available values can be found
here. The default is the local time zone, as set by your operating system.

timezone: TIMEZONE

Encoding

Set the encoding of files by name (only available for Ruby
1.9 or later).
The default value is utf-8 starting in 2.0.0,
and nil before 2.0.0, which will yield the Ruby
default of ASCII-8BIT.
Available encodings can be shown by the
command ruby -e 'puts Encoding::list.join("\n")'.

Destination folders are cleaned on site builds

The contents of <destination> are automatically
cleaned, by default, when the site is built. Files or folders that are not
created by your site will be removed. Some files could be retained
by specifying them within the <keep_files> configuration directive.

Do not use an important location for <destination>; instead, use it as
a staging area and copy files from there to your web server.

Enable the experimental incremental build feature. Incremental build only
re-builds posts and pages that have changed, resulting in significant performance
improvements for large sites, but may also break site generation in certain
cases.

incremental: BOOL

-I, --incremental

Liquid profiler

Generate a Liquid rendering profile to help you identify performance bottlenecks.

profile: BOOL

--profile

Serve Command Options

In addition to the options below, the serve sub-command can accept any of the options
for the build sub-command, which are then applied to the site build which occurs right
before your site is served.

Setting

Options and Flags

Local Server Port

Listen on the given port.

port: PORT

--port PORT

Local Server Hostname

Listen at the given hostname.

host: HOSTNAME

--host HOSTNAME

Base URL

Serve the website from the given base URL

baseurl: URL

--baseurl URL

Detach

Detach the server from the terminal

detach: BOOL

-B, --detach

Skips the initial site build.

Skips the initial site build which occurs before the server is started.

--skip-initial-build

X.509 (SSL) Private Key

SSL Private Key.

--ssl-key

X.509 (SSL) Certificate

SSL Public certificate.

--ssl-cert

Do not use tabs in configuration files

This will either lead to parsing errors, or Bunto will revert to the
default settings. Use spaces instead.

Custom WEBrick Headers

You can provide custom headers for your site by adding them to _config.yml

Defaults

We provide by default Content-Type and Cache-Control response headers: one
dynamic in order to specify the nature of the data being served, the other
static in order to disable caching so that you don’t have to fight with Chrome’s
aggressive caching when you are in development mode.

Specifying a Bunto environment at build time

In the build (or serve) arguments, you can specify a Bunto environment and value. The build will then apply this value in any conditional statements in your content.

For example, suppose you set this conditional statement in your code:

{%ifbunto.environment=="production"%}{%includedisqus.html%}{%endif%}

When you build your Bunto site, the content inside the if statement won’t be run unless you also specify a production environment in the build command, like this:

BUNTO_ENV=production bunto build

Specifying an environment value allows you to make certain content available only within specific environments.

The default value for BUNTO_ENV is development. Therefore if you omit BUNTO_ENV from the build arguments, the default value will be BUNTO_ENV=development. Any content inside {% if bunto.environment == "development" %} tags will automatically appear in the build.

Your environment values can be anything you want (not just development or production). Some elements you might want to hide in development environments include Disqus comment forms or Google Analytics. Conversely, you might want to expose an “Edit me in GitHub” button in a development environment but not include it in production environments.

By specifying the option in the build command, you avoid having to change values in your configuration files when moving from one environment to another.

Front Matter defaults

Using YAML Front Matter is one way that you can specify configuration in the pages and posts for your site. Setting things like a default layout, or customizing the title, or specifying a more precise date/time for the post can all be added to your page or post front matter.

Often times, you will find that you are repeating a lot of configuration options. Setting the same layout in each file, adding the same category - or categories - to a post, etc. You can even add custom variables like author names, which might be the same for the majority of posts on your blog.

Instead of repeating this configuration each time you create a new post or page, Bunto provides a way to set these defaults in the site configuration. To do this, you can specify site-wide defaults using the defaults key in the _config.yml file in your project’s root directory.

The defaults key holds an array of scope/values pairs that define what defaults should be set for a particular file path, and optionally, a file type in that path.

Let’s say that you want to add a default layout to all pages and posts in your site. You would add this to your _config.yml file:

defaults:-scope:path:""# an empty string here means all files in the projectvalues:layout:"default"

Please stop and rerun `bunto serve` command.

The _config.yml master configuration file contains global configurations
and variable definitions that are read once at execution time. Changes made to _config.yml
during automatic regeneration are not loaded until the next execution.

Note Data Files are included and reloaded during automatic regeneration.

Here, we are scoping the values to any file that exists in the path scope. Since the path is set as an empty string, it will apply to all files in your project. You probably don’t want to set a layout on every file in your project - like css files, for example - so you can also specify a type value under the scope key.

defaults:-scope:path:""# an empty string here means all files in the projecttype:"posts"# previously `post` in Bunto 2.2.values:layout:"default"

Now, this will only set the layout for files where the type is posts.
The different types that are available to you are pages, posts, drafts or any collection in your site. While type is optional, you must specify a value for path when creating a scope/values pair.

As mentioned earlier, you can set multiple scope/values pairs for defaults.

With these defaults, all posts would use the my-site layout. Any html files that exist in the projects/ folder will use the project layout, if it exists. Those files will also have the page.authorliquid variable set to Mr. Hyde.

collections:my_collection:output:truedefaults:-scope:path:""type:"my_collection"# a collection in your site, in plural formvalues:layout:"default"

In this example, the layout is set to default inside the
collection with the name my_collection.

Precedence

Bunto will apply all of the configuration settings you specify in the defaults section of your _config.yml file. However, you can choose to override settings from other scope/values pair by specifying a more specific path for the scope.

You can see that in the second to last example above. First, we set the default layout to my-site. Then, using a more specific path, we set the default layout for files in the projects/ path to project. This can be done with any value that you would set in the page or post front matter.

Finally, if you set defaults in the site configuration by adding a defaults section to your _config.yml file, you can override those settings in a post or page file. All you need to do is specify the settings in the post or page front matter. For example:

# In _config.yml...defaults:-scope:path:"projects"type:"pages"values:layout:"project"author:"Mr.Hyde"category:"project"...

Liquid Options

Liquid’s response to errors can be configured by setting error_mode. The
options are

lax — Ignore all errors.

warn — Output a warning on the console for each error.

strict — Output an error message and stop the build.

Markdown Options

The various Markdown renderers supported by Bunto sometimes have extra options
available.

Redcarpet

Redcarpet can be configured by providing an extensions sub-setting, whose
value should be an array of strings. Each string should be the name of one of
the Redcarpet::Markdown class’s extensions; if present in the array, it will
set the corresponding extension to true.

Bunto handles two special Redcarpet extensions:

no_fenced_code_blocks — By default, Bunto sets the fenced_code_blocks
extension (for delimiting code blocks with triple tildes or triple backticks)
to true, probably because GitHub’s eager adoption of them is starting to make
them inescapable. Redcarpet’s normal fenced_code_blocks extension is inert
when used with Bunto; instead, you can use this inverted version of the
extension for disabling fenced code.

Note that you can also specify a language for highlighting after the first
delimiter:

```ruby
# ...ruby code
```

With both fenced code blocks and highlighter enabled, this will statically
highlight the code; without any syntax highlighter, it will add a
class="LANGUAGE" attribute to the <code> element, which can be used as a
hint by various JavaScript code highlighting libraries.

smart — This pseudo-extension turns on SmartyPants, which converts
straight quotes to curly quotes and runs of hyphens to em (---) and en (--) dashes.

Once you’ve created your class and have it properly set up either as a plugin
in the _plugins folder or as a gem, specify it in your _config.yml:

markdown:MyCustomProcessor

Incremental Regeneration

Incremental regeneration is still an experimental feature

While incremental regeneration will work for the most common cases, it will
not work correctly in every scenario. Please be extremely cautious when
using the feature, and report any problems not listed below by
opening an issue on GitHub.

Incremental regeneration helps shorten build times by only generating documents
and pages that were updated since the previous build. It does this by keeping
track of both file modification times and inter-document dependencies in the
.bunto-metadata file.

Under the current implementation, incremental regeneration will only generate a
document or page if either it, or one of its dependencies, is modified. Currently,
the only types of dependencies tracked are includes (using the
{% include %} tag) and layouts. This means that plain
references to other documents (for example, the common case of iterating over
site.posts in a post listings page) will not be detected as a dependency.

To remedy some of these shortfalls, putting regenerate: true in the front-matter
of a document will force Bunto to regenerate it regardless of whether it has been
modified. Note that this will generate the specified document only; references
to other documents’ contents will not work since they won’t be re-rendered.

Incremental regeneration can be enabled via the --incremental flag (-I for
short) from the command-line or by setting incremental: true in your
configuration file.