The Stochastic Game

Ramblings of General Geekery

Upgrading to PieCrust 2

The recently announced PieCrust 2 is all fine and dandy if you were to
create a new website – the command line interface and user experience are
essentially the same out of the box – but you will find that it can’t handle an
existing PieCrust 1 website. This is because a few things have changed…
luckily, the chef import command and this blog post will get you going in no
time!

Installing PieCrust 2

First, get PieCrust 2 on your system:

  • Install Python 3.
  • Run pip install piecrust in a console.

If you want to install the bleeding edge (read “unstable”) version directly from
BitBucket or GitHub, instead of the latest posted release from the
Python package manager, you can do one of:

  • pip install hg+https://bitbucket.org/ludovicchabant/piecrust2#egg=PieCrust
  • pip install git+https://github.com/ludovicchabant/PieCrust2.git#egg=PieCrust

There are many other options if you want to install PieCrust for advanced
scenarios. See the pip documentation.

Check that everything’s OK by running chef --version. At the time of writing,
you should get something like 2.0.0-alpha2.

Note: If you still get a 1.x version, you probably have the PieCrust 1
directory showing up first in your PATH environment variable, so go change
that (or delete PieCrust 1 altogether!).

Upgrading a PieCrust 1 website

The chef import command was previously used for importing
content from other CMSes like WordPress. Now it can also import content from a
PieCrust 1 website, and even upgrade it in place. Get in your website and try:

chef import piecrust1 --upgrade

You’ll notice that a lot of things got moved. The previous layout for a website
looked like this:

+ root
|- _cache/
|- _content/
|     |- config.yml
|     |- pages/
|     |- posts/
|     |- templates/
|- css/
|- images/
|- lots/
|- of/
|- other/
|- crap/
|- whatever
|- .gitstuff

Now it looks like this:

+ root
|- _cache/
|- assets/
|     |- css/
|     |- images/
|     |- other-crap/
|- pages/
|- posts/
|- templates/
|- config.yml
|- whatever
|- .gitstuff

Basically, the _content directory is gone… everything got moved up one
level, while all the asset files (CSS, images, fonts, etc.) got moved into an
asset folder1.

The benefits of this change are:

  • It looks better! There’s no more mix of different “things” at the root level
    (magic folders, assets, source-control files, miscellaneous things…).
    Instead, “things” are arranged in different folders that are almost
    self-explanatory (mostly because you can choose them!).
  • All the assets that should be processed and copied as part of the bake are in
    assets. Anything that’s only for development purposes (source control files,
    miscellaneous stuff) can be in the root directory, or in a different folder
    than assets, and they won’t be picked up by the bake. This prevents a lot of
    oh shit” moments where you forgot to add something to the
    baker/skip_patterns config and a whole bunch of files are baked but you
    didn’t mean to.
  • It’s going to be easier to manage interoperability with other tools such as
    Grunt, by having such external tools operate on other top-level
    directories.

A few other things also changed, mainly because of the move from Twig to
Jinja as the default templating engine. Although they’re very similar, they
do have some differences in terms of built-in functions and filters.

  • An example is that Twig’s slice filter maps to an array notation in Jinja
    (so {{items.slice(3, 6)}} becomes {{items[3:6]}}), and Jinja’s slice does something completely
    different
    (although very useful)!
  • Another example is date formatting, which is different between PHP
    and Python.

The importer will try to fix those things automatically for you (or at least
warn you about it and provide guidance), but it’s probably going to miss a few
ones since I only know about those I ran into while upgrading my own websites.
Please report any such problems, thanks.

Unsupported features

PieCrust 2 is not quite feature complete compared to PieCrust 1 – I can’t
reasonably wait until 100% of the feature set is implemented before getting it
out there for feedback.

Here are things I know are missing:

  • Running as a CMS: there’s not much code needed for that, but there’s no WSGI
    application class yet.
  • A plugin API: not much code needed yet either, but yeah, you can’t at the
    moment drop anything in the plugins folder, it won’t get loaded.
  • Slugification of taxonomies: tags and categories containing non-ASCII
    characters will keep them for now. PieCrust 1 had options for transliterating
    them into their non-accentuated/ASCII counter-parts.
  • Support for RSS/Atom feed scaffolding (chef prepare feed).
  • Mustache as an alternative template engine.

There are also probably things I don’t know are missing, so make sure you
ping me if something you care about is not on this list.

In the next blog post, we’ll finally take a look at the new features in PieCrust
2, including the completely new underlying system for specifying pages,
taxonomies, and URLs.


  1. Don’t worry, it’s configurable. You can put your asset files in a
    different folder, or even in multiple folders. ↩︎