Ramblings of General Geekery

PieCrust 3.0

Last year I announced PieCrust 2.0 without much fanfare and, guess what, here comes PieCrust 3.0 now!

The funny thing is that I didn’t post much about PieCrust during that whole time… the joke about blog engines is that the more you work on them, the less you actually use them.

So as is tradition, I released the new version of PieCrust on the Python package server and immediately found a bunch of new bugs, which I proceeded to fix (we’re now at PieCrust 3.1.1)… I’m not very good at this whole thing, even after several years.

But either way, it’s out! You can run pip install piecrust -U and read the rest of this post if you want to know what’s new.

This release has breaking changes so make sure you read the upgrade notes this time around.

The highlights in this release include:

  • Simplified content model: there are now just content sources and URL routes. The previous “page generator” concept (which was used for taxonomies and blog archives) is now just a content source that happens to not return pages on disk, and instead comes up with pages on the fly. This makes things a bit simpler for the site configuration.

    There is a new concept however, which is the concept of a “content pipeline”, which is the thing that knows how to render a source’s contents. It’s a lot less user facing though – in most cases users don’t need to bother with it.

  • Better administration panel: the administration panel now supports talking to client apps (via the Micropub standard) to create new posts. This means you can post to your static website from your phone with apps like Micro.blog! This requires some server-side setup however, so you have some work to do.

    In the PieCrust 3.0 cycle I’ll actually be mostly looking at adding more IndieWeb technologies like MicropubWebmention is next, which will let your site display comments.

  • Watchdog-enabled chef server: when you run chef serve, you can have PieCrust monitor your assets (like CSS/JS files) and re-process them when you edit them (unless you’re using another more sophisticated asset pipeline like Gulp or Webpack or whatever). In PieCrust 2.0 it was using a very basic polling system, but now it’s using Watchdog, which means it works with your OS to get notified of file changes. The main upside is a more efficient file monitoring that’s a lot more battery friendly for laptop users.

As always, if you see any bug, report it on the GitHub issue tracker.

Piecrust 2.0 and Beyond

As is tradition, PieCrust 2.0 was released without much fanfare a few weeks ago. Just like with the previous version, it just happened because, well, nothing happened: I was using PieCrust for a couple other websites without any problem or need for new features, so I figured it might be as good a time as any to make it official.

Time to run pip install -U piecrust.

Since then of course I found a few bugs, so a 2.0.1 release is just around the corner, but that’s just business as usual.

What’s more interesting, first, is that I’ve been a bit quiet over here for the past couple months, and that’s because I was busy with my second hacking project from the holiday break (the first one of which was the recently announced Jouvence). Sadly it didn’t really pan out like I expected, so after working on it for a while I’ve now shelved it for the time being. These things happen.

The second thing is that I started work on PieCrust 3.0. It’s a mess right now but the goal there is to get rid of a bunch of cruft that accumulated over the years. As such, it will break backwards compatibility quite a lot (hence the major version bump) but I’m hopeful the result will be easier to use, easier to
maintain, and maybe even hopefully a bit faster.

PieCrust 2.0rc2

PieCrust 2.0rc2 was published a couple days ago, and it’s mostly a bug fix and clean-up release, as you might expect. Run your pip install piecrust --pre -U to update, or whatever you do usually. More info after the jump.

Since there are mostly bug fixes in this release, there’s only a few small user-facing change to discuss here.

SFTP publisher

Are you using the recent new publishing features? You should! Now there’s an SFTP publisher. See the publishers reference for details.

Simplified URL functions

I did some simplification of the way URL routing is handled. The biggest change is that URL functions now don’t need to specify their parameters. Here’s how it works:

  • You define a custom source… for instance the PieCrust documentation site defines 2 separate sources, one for the user documentation and one for the API documentation.
  • In the routes defined for those 2 sources, you can specify a func property which is the name of a function available through the template engine to generate URLs for these routes. In the aforementioned documentation configuration, these functions are docurl and apiurl (so one documentation page can link to another by writing {{docurl('something/else')}} for example).
  • The parameters to pass to the URL function are the same as the placeholders in the URL itself… so if the route is /blog/%year%/%slug%, you need to pass the year and the slug into the function ({{posturl(2016, 'my-new-post')}}).

You can see the (updated) documentation on routes for more details.

Merged taxonomy terms

By default, PieCrust “slugifies” your taxonomy terms (like tags) using URL encoding, so that something like “étrange” (“strange” in French… not the accented first letter) is transformed into “%C3%A9trange” (which your browser will properly show as “étrange”).

However, you can also tell PieCrust to do different slugification1, with the site/slugify_mode configuration setting. So say you set it to lowercase,transliterate… it will transform your tag names to lowercase and replace accented and non-latin characters with their closest equivalent. In this case, “étrange” gets slugified to “etrange” (without the accent), and “Technology” gets replaced with “technology” (lowercase).

Of course, it means that 2 slightly different tags can resolve to the same slugified tag – for example, “étrange” and “Etrange”. In this case, PieCrust will now warn you that you spelled things differently in some pages, but will combine both – i.e. the page listing for the term “étrange” will also list the posts where you spelled it “Etrange”.

As always, the full list of changes is available on the CHANGELOG.

  1. Yes, that’s totally a word a made up. ↩︎

Baking faster with hoedown

Update: the times reported by the Bench utility are CPU times, i.e. they represent the time spent working by your various CPUs. The “real/wall” time, i.e. the time you effectively have to wait as a user, is usually a third less than that. So the “real” time for my blog went roughly from 7 seconds to 5 seconds.

In a previous blog post about PieCrust performance, I mentioned how static site generators are dependent on the performance of their formatting and templating libraries. One of the most common formatters are Markdown formatters and, by default, PieCrust uses Python Markdown. It’s the easiest one to install and use, but it’s far from the fastest one.

As far as I know, the fastest one that’s still maintained is Hoedown, for which some Python bindings exist. And if you have a recent enough version of PieCrust, there will be support for a Hoedown formatter, as long as you install Hoedown. You can do that by running pip install hoedown.

Once installed, you can make replace Markdown with Hoedown by writing this in your config.yml, or in a config variant:

    default_format: hoedown
        md: hoedown

Any extensions you have declared for the Markdown formatter generally also translate directly to Hoedown:

    extensions: [fenced_code, footnotes, smartypants]

The performance increase can be pretty noticeable. For instance, on my ancient MacBook Pro (2.4GHz Core 2 Duo), this blog takes almost 9 seconds to bake1:

With Hoedown, the time goes down to 7.2 seconds:

Pretty worth it if you ask me! Now most of the time spent baking happens during templating with Jinja2… time to look for a faster alternative?

  1. I used the Bench tool to generate those reports. ↩︎

Piecrust 2.0rc1

PieCrust 2.0rc1 is now out! The last piece of the puzzle (or should I say the pie?), page generators, is now in place.

You can run pip install piecrust --pre -U to update from PyPi, or grab it from BitBucket or GitHub.

More details after the break.

Page generators

The big new feature in this release are page generators. They’re basically a generalization of the previous taxonomy feature, which used to let you define taxonomies (tags, categories, etc) to classify your pages, and then PieCrust would generate one page for each term that you use (e.g. each tag would get its own page).

But the concept of generating pages based on what’s in the “normal” pages is also useful for other things… for instance, blog archives – assuming you don’t want all your archives to be in one page, like you had to do before. Instead, you could have one page per year, for instance.

That’s exactly what PieCrust 2.0rc1 ships with – a yearly blog archive generator, in addition to the taxonomy system. By default, if you create a pages/_year.md page, it will start creating yearly archive pages based on it.

Page generators benefit from the same kind of parallelism and caching that all other page sources have during a bake, so it should be as fast as before.

For more information on page generators, see the new documentation page.


Other improvements in this release include bake performance improvements, fixes with the administration panel (FoodTruck), and various fixes.

For a full list of changes, you can actually see the new fancy online changelog.

Piecrust Drives A Truck

PieCrust 2.0 beta 5 is now live on PyPi, so you can go ahead and pip install --pre piecrust -U to get it.

The 2 big new features in that release are the last reasons I switched to Python for PieCrust 2 after packaging and multi-core support: better ways to launch and manage sub-processes. This lets me do:

  • Publishing support, because baking your site is only the beginning, and you actually need to upload that stuff somewhere.
  • FoodTruck”, an optional administration panel to work on your site(s) the same way you would with a traditional system like WordPress.

More after the break.


A lot of static website generators out there already have this concept of “publishing” your website, i.e. not only bake it, but also upload it to some FTP server, rsync it, push it to GitHub pages or an S3 bucket or whatever. Support varies from system to system.

Well now PieCrust at least has the basic infrastructure to support the same kind of feature – something I have been delaying for too long! There’s only support for arbitrary shell commands and rsync, but I’m hoping more publish targets will come soon.

For more information, see the documentation on publishing your website.


I’ve wanted to do this for a while now, but had to figure out the right way to do it, which is to provide a web administration dashboard that you can use to work on your website.

Now I know what you’re thinking. Isn’t the whole point of static website generators that you keep everything simple as text files, and you use your favorite (and most productive) text editor? Well, of course!

But the reality is that you need an optional adminstration panel for 2 reasons:

  • First, you want to attract newbies and non-technical people to the dark side of flat-file CMSes. Making it attractive and usable to them will hopefully be one of the gateways for them to become more technical, and in turn maybe participate in this wonderful melting pot that is the open-source
  • Second, have you seen the average blogging frequency of a static website user? Have you seen mine1? I believe that it’s a consequence of the price we pay in terms of practicality: to post something new, we have to get to a computer that has our site repo, and some way to bake and upload that to our web server. But it doesn’t have to be that way. You could also have an administration panel running on your server, so that you can also quickly post on the move, from your phone, and it would take care of baking and publishing for you in the background.

As I was writing FoodTruck, a couple static website generators appeared with an administration panel – most famously Lektor, by Python superstar “mitsuhiko”2. As far as I can tell, these are mostly geared towards the first reason, i.e. provide a nicer, user-friendly way to edit your website.

Hopefully, they start moving towards the second reason too. That second reason is actually the heart of FoodTruck, although there’s still a lot of work to get there. Consider:

  • The administration panel needs to run some heavy process (baking and publishing) from a web page.
  • The administration panel needs to be able to submit to your Git/Hg/etc. repository so you can then pull the edits you made on the go once you get back home.
  • The administration panel needs to be secure, obviously. And I don’t know shit about web security.

It can do most of that already, but not well enough yet for me to be comfortable with letting you all run this code on a public web server… so stay tuned for the next few releases, and check out the documentation on the administration panel for more info.

  1. Ironically enough, my blogging frequency went down around the time I started writing my own blog system… although that’s slightly misleading, because that’s also around the time I started having kids, and coincidentally figured I should focus more on fewer home projects in order to actually ship them, instead of always leaving them in a half-finished state. ↩︎

  2. There go my chances of having the most popular Python static website generator! ↩︎

Wikked 0.6.5

This looks like a small update for Wikked but it’s kind of the reason this blog has been so quiet lately…

If you don’t want to hear about it, just know this:

If you want the full story, keep reading.

Back to the 90’s

I originally wrote Wikked as a single page app because, well, I wanted to have a little fun and learn something new. And it worked (I did have fun learning Javascript past the “copy JQuery snippets from the internet” phase), but it didn’t really work (it made testing and deploying unnecessarily harder). It could have also been argued that making this an SPA was overkill… at least, it did bother me a bit, since I tend to prefer simpler/old-school technologies.

Anyway, I embarked on a giant refactor of the code base to reimplement the front-end using a more classic architecture, and the last couple versions of Wikked are the result of this transition. You shouldn’t see anything new, besides a few less old bugs, a few new bugs, and an overall more stable

New documentation

In the process, I also got rid of the old documentation page I had on BOLT80, and made a proper versioned documentation website, just like with PieCrust. That website is part of the Wikked codebase so you can easily send patches for it… and of course, it’s made with PieCrust.

You can check it out at the same place as before on BOLT80. It’s still a work in progress design-wise – it’s meant to look similar to a Wikked-powered wiki, but it still lacks a bit of graphics and other stuff to make it look less sterile.

Next steps

As always after I spend a few months doing some giant task with the limited free time that I have, I need to get back to my other projects and reply to the various bug reports and pull requests I haven’t replied to in weeks. Then it’s back to business as usual, I hope… at least unless I get into another big refactor.

Multi-core PieCrust 2

PieCrust news – and this blog – have been pretty quiet for the past couple months, and that’s because I’ve been busy working on PieCrust 2 performance.

"pasticcetti con crema e amarene" - mini-pies with custard and sour cherries

TL;DR: PieCrust 2 now runs in multiple cores, which speeds up the baking process quite a bit. Update your repositories, or grab the latest version from Pypi!

More details after the break.

Read more…

Piecrust 1.x is Officially Deprecated

It had to happen eventually, but PieCrust 1.x is now officially deprecated. It was deprecated more or less unofficially before, as you can see from the lack of activity on the repository, but, well, here it is.

PieLab: Empty Plate

The PieCrust 2 help pages are now showing up by default at the official URL, and that’s where I’ll be focusing from now on.

If you want to upgrade your existing 1.x website to 2.0, you can follow the installation and upgrade instructions. And of course, please contact me if you have issues or feedback!