Mercurial > piecrust2

--- /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:
+
+    <p>This page lists all the recipes written so far in Ludovic&#8217;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>
+
+
+### 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:
+
+    <html>
+    <head><title>{{page.title}}</title></head>
+    <body>
+    {{content|raw}}
+    </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&#8217;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:
+
+* [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)
+