--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/docs/01_tutorial.md	Thu Feb 19 23:30:08 2015 -0800
@@ -0,0 +1,12 @@
+---
+title: Tutorial
+---
+
+This PieCrust tutorial will walk you through the process of creating a new
+website, writing content for it, customizing its appearance, and publishing it
+somewhere.
+
+{% for part in family.children %}
+* [{{part.title}}]({{part.url}})
+{% endfor %}
+

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/docs/01_tutorial/01_your-first-blog.md	Thu Feb 19 23:30:08 2015 -0800
@@ -0,0 +1,215 @@
+---
+title: "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"][1] page.
+
+Let's also verify you have an up-to-date version of PieCrust.
+
+    $ chef --version
+    {{piecrust.version}}
+
+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][2].
+
+
+## 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 address
+`http://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][pageconfref].
+
+
+## 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][slug]. 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][siteconfref] 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][part2] 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.
+
+
+
+[1]: {{pcurl('getting-started')}}
+[2]: {{piecrust.url}}
+[yaml]: https://en.wikipedia.org/wiki/YAML
+[slug]: http://en.wikipedia.org/wiki/Semantic_URL#Slug
+[pageconfref]: {{pcurl('docs/reference/page-config')}}
+[siteconfref]: {{pcurl('docs/reference/site-config')}}
+[part2]: {{pcurl('docs/tutorial/making-things-pretty')}}
+