Part 1: Your First Blog

This tutorial walks you through the creation of your first PieCrust website: a simple blog.

Whenever you see something like this:

$ chef blah --something

It means you need to run that command (starting with chef) in a terminal or command prompt. Text that doesn’t start with the dollar sign is the expected output of the command.

We’ll assume you already have installed PieCrust on your system. If not, the installation steps are documented in the “Getting Started” page.

Let’s also verify you have an up-to-date version of PieCrust.

$ chef --version
3.0.2+32.1a214de1e1f7

If your version is older, you’ll want to update PieCrust:

$ pip install piecrust -U

If your version is newer, you’re probably looking at old docs! You should be able to find newer docs at the official PieCrust website.

Create the website

Creating the website can be done with a simple command:

$ chef init myblog

This will create a directory called myblog in the current directory, and initialize a PieCrust website in it. If you go inside and look at the contents, however, you’ll be surprised to find that there’s not much:

$ cd mblog
$ ls
config.yml

There’s just a config.yml file! But that’s the file that differentiates a random directory with a PieCrust website. PieCrust expects a file named like that at the root of a website.

Because PieCrust websites are all files (mostly text), they fit really nicely in a source control repository. This makes it so much easier to backup and rollback than with a website running on an SQL database, like Wordpress.

It’s recommended that you create such a repository right now. If you want to use Git, you would type:

$ git init .
$ git add .
$ git commit -m "Initial empty blog."

If you want to use Mercurial, you would type the same commands, but replace git with hg. For other source control systems, please check the documentation.

And of course don’t forget to commit your changes as you go!

Preview the website

At this point, you only have an empty website, but we can still preview it in the browser! Type:

$ chef serve
* Running on http://localhost:8080/

It should tell you it’s started a web server at the addresshttp://localhost:8080. If you type that in your browser’s address bar, you should see PieCrust’s welcome and boilerplate page.

You may notice that the serve command is still running. That’s because the server is still running, which is what you want. You can stop the server by hitting CTRL+C at any time, but that means the preview won’t work anymore. And because we still have some work to do, obviously, you’ll want to open a new terminal or command prompt in order to type new commands.

Now let’s add some stuff!

Add some posts

To add posts, you just have to create a text file in the correct place with the correct name. By default, PieCrust expects posts in the posts/ directory, with a name like so: YYYY-MM-DD_title-of-the-post.md.

If you’re like me, you probably don’t know what today’s date is, however. And there’s also the risk of a typo… so let’s instead use the prepare command:

$ chef prepare post my-first-post
Creating page: posts/2015-02-19_my-first-post.md

There, it tells you the path of the file it created. Open that file now in your favorite text editor. You should see something like this:

---
title: My First Post
time: '08:21:49'
---

This is a brand new page.

Refresh your browser, and you should see that post instead of the welcome page. Edit the post’s text (under the second --- line), and refresh your browser.

Now let’s add another post. Run the prepare command again:

$ chef prepare post my-second-post
Creating page: posts/2015-02-19_my-second-post.md

Refresh your browser, and you can see how your blog’s homepage is starting to shape up as expected, with a reverse-chronological list of your posts. That’s because the default theme for new PieCrust websites defines a page template for the home page that does exactly that. This can totally be overriden, of course, but it works well as an out-of-the-box experience.

If you want to change the title of a post, you can edit the title: part in the posts’ configuration header (which is what we call that part between the 2 --- lines). However, the URL of the post will still have my-first-post or my-second-post in it. If you want to change that, you’d have to rename the file itself.

The configuration header is written in YAML. It’s usually fairly straightforward, but the first hurdle you may run into is if you want to set a title to something with characters like ' or : in them. In this case, you’ll have to add double-quotes (") around the whole thing.

If you’re using a decent text editor with syntax highlighting, it should know about the YAML syntax and tell you that something’s wrong.

Similarly, if you want to change the date of a post, you’d have to rename the file. The time of the post is in the configuration header, though, so you can tweak that in the text file.

To know more about the different settings you can change in a page’s configuration header, check out the page configuration reference.

Add some pages

Just like posts, pages are text files placed in some specific directory – the appropriately named pages/ directory. If you create a pages/foo.md file, you’ll get a /foo.html page in your published website (or just /foo if you don’t want URLs ending with .html).

Let’s create an “About” page for our blog. Once again, we could create the text file “by hand” but we can also use the prepare command:

$ chef prepare page about
Creating page: pages/about.md

Edit that file and change it to something more appropriate… make the title something like “About This Site”, and add some text.

You should still have the server running, so type http://localhost:8080/about.html in the address bar. You should see your new page show up.

Of course, you probably want a link to that page – it’s not very useful if visitors have to know the URL in order to reach it. We could go into layout and templating considerations so that we can add it in some kind of sidebar menu, but we’ll keep this tutorial short for now. Instead, let’s just add a link to it from one of your blog posts.

Open your last created post in a text file, and add something like this:

You can learn more [about this site here]({{pcurl('about')}})

Go back to the home page (http://localhost:8080) in your browser and look for that new piece of text. It should feature a hyperlink to your new “About” page.

Here’s how this worked:

  • The [text here](url) syntax is Markdown for hyperlink. All the posts and pages files have a .md extension, which means PieCrust will use Markdown to format it. This means you can use things like *asterisks* and **double asterisks** to show italics and bold things. See any Markdown cheat sheet to learn about this simple syntax.

  • As mentioned above, the part in parenthesis is supposed to be the URL of the hyperlink, so you might be wondering why we’re writing this weird {{pcurl('about')}} thing instead of just something like /about.html.

    The reason is that a fixed URL is easy to break – when you change the root URL of your site, or when you change between “ugly” URLs (with the .html extension) and “pretty” URLs (without the extension), along with a few other possible changes.

    The pcurl function generates the URL according to the current situation and is therefore much more versatile. You can read more on routing and URL functions, or more on templating in general.

Configuring the website

This is all fine and dandy, but the big title at the top of the home page still says “My New Website”, and that’s not very personal. Let’s configure that.

Open the config.yml file. It’s also written in YAML, like the posts’ configuration headers. You can change the site/title setting easily:

site:
    title: "Ludovic's Blog"

Note how, for the rest of this tutorial (and the rest of the documentation!) we’ll refer to nested configuration settings using slash separators. So the site/title setting refers to the title setting inside the site setting, as shown in the snippet above.

Refresh your browser, and lo and behold, the new title should be there.

There are plenty of other things you can configure in the config.yml file. For example, say you don’t like the default URL format for posts. That can be adjusted with the site/post_url setting. By default, it is:

site:
    post_url: "%year%/%month%/%day%/%slug%"

The post URL format is defined using some keywords surrounded by percent signs, as you can see above. The %year%, %month% and %day% keywords should be self-explanatory – and they map directly to the post’s filename, which, if you remember, contains the post’s date.

The %slug% keyword maps to the post’s “slug”, which is the part of the URL that has human-readable words. In PieCrust’s case, it comes from the part of the filename that comes after the date (“my-first-post and my-second-post in this tutorial).

If, say, your blog has a low chance of slug collision, or has a low post frequency, and you want to have more minimal URLs, you can change it to:

site:
    post_url: "%year%/%slug%"

Refresh your browser, and you should see that the posts’ URLs are now conforming to the new format.

If your browser was currently displaying a post at the old URL, you will suddenly get a “page not found” error! That’s OK, it’s because the post is now at the new, shorter URL. Just go back to the root URL, localhost:8080.

See the site configuration reference for more information about all the settings you can change.

Next steps

At this point you have a moderately function blog, but it’s far from looking good yet. In the second part of this tutorial we’ll look at customizing your website’s appearance by editing layouts and templates, and writing CSS stylesheets and using PieCrust’s built-in asset pipeline.