Upgrading from 0.x to 2.x

Upgrading from an older version of Bunto? A few things have changed in 1.0 and 2.0 that you’ll want to know about.

Before we dive in, go ahead and fetch the latest version of Bunto:

$ gem update bunto

Diving in

Want to get a new Bunto site up and running quickly? Simply run bunto new SITENAME to create a new folder with a bare bones Bunto site.

The Bunto Command

For better clarity, Bunto now accepts the commands build and serve. Whereas before you might simply run the command bunto to generate a site and bunto --server to view it locally, in v2.0 (and later) you should use the subcommands bunto build and bunto serve to build and preview your site.

Watching and Serving

With the new subcommands, the way sites are previewed locally changed a bit. Instead of specifying server: true in the site’s configuration file, use bunto serve. The same holds true for watch: true. Instead, use the --watch flag with either bunto serve or bunto build.

Absolute Permalinks

In Bunto v1.0, we introduced absolute permalinks for pages in subdirectories. Starting with v2.0, absolute permalinks are opt-out, meaning Bunto will default to using absolute permalinks instead of relative permalinks. Relative permalink backwards-compatibility was removed in v3.0.

Absolute permalinks will be required in v3.0 and on

Starting with Bunto v3.0, relative permalinks functionality will be removed and thus unavailable for use.

Draft Posts

Bunto now lets you write draft posts, and allows you to easily preview how they will look prior to publishing. To start a draft, simply create a folder called _drafts in your site’s source directory (e.g., alongside _posts), and add a new markdown file to it. To preview your new post, simply run the bunto serve command with the --drafts flag.

Drafts don’t have dates

Unlike posts, drafts don’t have a date, since they haven’t been published yet. Rather than naming your draft something like 2013-07-01-my-draft-post.md, simply name the file what you’d like your post to eventually be titled, here my-draft-post.md.

Custom Config File

Rather than passing individual flags via the command line, you can now pass an entire custom Bunto config file. This helps to distinguish between environments, or lets you programmatically override user-specified defaults. Simply add the --config flag to the bunto command, followed by the path to one or more config files (comma-delimited, no spaces).

As a result, the following command line flags are now deprecated:

--no-server
--no-auto (now --no-watch)
--auto (now --watch)
--server
--url=
--maruku, --rdiscount, and --redcarpet
--pygments
--permalink=
--paginate

The config flag explicitly specifies your configuration file(s)

If you use the --config flag, Bunto will ignore your _config.yml file. Want to merge a custom configuration with the normal configuration? No problem. Bunto will accept more than one custom config file via the command line. Config files cascade from right to left, such that if I run bunto serve --config _config.yml,_config-dev.yml, the values in the config files on the right (_config-dev.yml) overwrite those on the left (_config.yml) when both contain the same key.

New Config File Options

Bunto 1.0 introduced several new config file options. Before you upgrade, you should check to see if any of these are present in your pre-1.0 config file, and if so, make sure that you’re using them properly:

excerpt_separator
host
include
keep_files
layouts
show_drafts
timezone
url

Baseurl

Often, you’ll want the ability to run a Bunto site in multiple places, such as previewing locally before pushing to GitHub Pages. Bunto 1.0 makes that easier with the new --baseurl flag. To take advantage of this feature, first add the production baseurl to your site’s _config.yml file. Then, throughout the site, simply prefix relative URLs with {{ site.baseurl }}. When you’re ready to preview your site locally, pass along the --baseurl flag with your local baseurl (most likely /) to bunto serve and Bunto will swap in whatever you’ve passed along, ensuring all your links work as you’d expect in both environments.

All page and post URLs contain leading slashes

If you use the method described above, please remember that the URLs for all posts and pages contain a leading slash. Therefore, concatenating the site baseurl and the post/page url where site.baseurl = / and post.url = /2013/06/05/my-fun-post/ will result in two leading slashes, which will break links. It is thus suggested that prefixing with site.baseurl only be used when the baseurl is something other than the default of /.

Back