# HG changeset patch # User Ludovic Chabant # Date 1424934637 28800 # Node ID dbd6813fb6dff1997c27a878641cecaf20ec48cc # Parent f8601540caff94f287edfe606206b936c4562af6 docs: Add a page explaining how PieCrust works at a high level. diff -r f8601540caff -r dbd6813fb6df docs/docs/02_general/04_how-it-works.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/docs/02_general/04_how-it-works.md Wed Feb 25 23:10:37 2015 -0800 @@ -0,0 +1,120 @@ +--- +title: How It Works +--- + +PieCrust websites are highly customizable, but they rely on a few simple +principles that you can learn in a minute. + + +## Page rendering + +PieCrust loads pages from [page sources][src], 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][def], these are the `pages/` and +`posts/` directories, which contain pages and blog posts respectively. + +Each page or post goes through the same process: + +1. Templating +2. Formatting +3. Layout rendering + +The first two steps render the page's contents, which can be split into [content +segments][seg]. 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 {{site.title}}: + + {%raw%} + {% for p in family.children %} + * [{{p.title}}]({{p.url}}) + {% endfor %} + {%endraw%} + + +### Templating + +Each segment first goes through [templating][tpl]. 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) + +### Formatting + +Next, the result goes through a [formatter][fmt], which will convert the +intermediate text into the final text. + +The default formatter is [Markdown][]. So our page becomes: + +

This page lists all the recipes written so far in Ludovic’s Blog:

+ + + +### Layout rendering + +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: + + + {{page.title}} + + {{content|raw}} + + + +...then our final page will be: + + + All Recipes + +

This page lists all the recipes written so far in Ludovic’s Blog:

+ + + + +Of course, we glossed over a lot of things here, which you will want to learn +about: + +* [Site configuration settings][siteconf]. +* [Page configuration settings][pageconf]. +* [Templating][tpl], and [Jinja's syntax][jinja]. +* [Formatting][fmt], with [Markdown][] or [Textile][]. + + +[src]: {{docurl('content-model/sources')}} +[def]: {{docurl('content-model/default-model')}} +[seg]: {{docurl('content/content-segments')}} +[tpl]: {{docurl('content/templating')}} +[fmt]: {{docurl('content/formatters')}} +[siteconf]: {{docurl('general/website-configuration')}} +[pageconf]: {{docurl('content/page-configuration')}} +[jinja]: http://jinja.pocoo.org/docs/dev/templates/ +[markdown]: https://en.wikipedia.org/wiki/Markdown +[textile]: https://en.wikipedia.org/wiki/Textile_(markup_language) +