PieCrust websites are highly customizable, but they rely on a few simple principles that you can learn in a minute.
PieCrust loads pages from page sources, which are most of the time a
sub-directory of your website’s root directory, with a bunch of text files in
them. For an out-of-the-box PieCrust website, these are the pages/ and
posts/ directories, which contain pages and blog posts respectively.
Each page or post goes through the same process:
The first two steps render the page’s contents, which can be split into content
segments. Most of the time, a page will only have one content segment,
appropriately called content. The third step optionally inserts these contents
into a re-usable piece of markup.
Let’s assume you have this in pages/recipes.md:
---
title: All Recipes
layout: simple
---
This page lists all the recipes written so far in PieCrust:
{% for p in family.children %}
* [{{p.title}}]({{p.url}})
{% endfor %}
Each segment first goes through templating. Various pieces of data will be exposed to the template engine for you to use in your page — the page’s configuration settings, the website’s configuration settings, utilities to create paginated content, access points to all pages or blog posts, etc.
The default template engine is Jinja.
If the site/title setting was set to “Ludovic’s Blog” in the config.yml
file, and there are a couple of recipe pages inside pages/recipes/, the
recipes.md page will come out of the templating phase like this:
This page lists all the recipes written so far in Ludovic's Blog:
* [Rhubarb Pie](/recipes/rhubarb-pie)
* [Pound Cake](/recipes/pound-cake)
Next, the result goes through a formatter, which will convert the intermediate text into the final text.
The default formatter is Markdown. So our page becomes:
<p>This page lists all the recipes written so far in Ludovic’s Blog:</p>
<ul>
<li><a href="/recipes/rhubarb-pie">Rhubarb Pie</a></li>
<li><a href="/recipes/pound-cake">Pound Cake</a></li>
</ul>
Last, the page’s templated and formatted contents are put inside a layout
(unless the page’s layout configuration setting is set to none). Since our
example page is using the simple layout, and if we assume the file
templates/simple.html looks like this:
<html>
<head><title>{{page.title}}</title></head>
<body>
{{content|safe}}
</body>
</html>
…then our final page will be:
<html>
<head><title>All Recipes</title></head>
<body>
<p>This page lists all the recipes written so far in Ludovic’s Blog:</p>
<ul>
<li><a href="/recipes/rhubarb-pie">Rhubarb Pie</a></li>
<li><a href="/recipes/pound-cake">Pound Cake</a></li>
</ul>
</body>
</html>
Of course, we glossed over a lot of things here, which you will want to learn about:
PieCrust comes with a very capable built-in asset pipeline to process your CSS and Javscript files, images, etc. It works very well for common use-cases, since it doesn’t require any kind of configuration — unlike other more powerful systems like Grunt or Gulp.
The PieCrust asset pipeline matches files to processors, in a recursive way — which means the outputs of a given processor are then potentially re-processed by others processors.
For instance, if you have a Less CSS file, it will be processed like so:
foo.less -> foo.css -> foo.min.css
Any LessCSS file (i.e. a file with the .less extension) will be compiled with
the LessCSS processor, which outputs a CSS file. This then gets picked up by
the CleanCSS processor, which will generate a compressed CSS file.
If you want more information about what processors are mapped to what file types, you can check the list of built-in processors. There’s also more information available about the asset pipeline.