Content segments

In PieCrust, pages define the content of your website when templates define (among other things) the layout of your website. As you’ll see in the templates documentation, the “placeholder” for the text of a page is called content. We also previously mentioned how the page configuration exposes anything defined in it, so you could in theory define other pieces of content in the configuration, like for instance a page-specific menu or sidebar text. This is not really practical, however, because the YAML syntax used for the page configuration is mostly designed for small things like configuration settings and one-liners.

Thankfully, PieCrust lets you define other “text segments” in addition to the default “content” segment. You do this by writing a line formatted like so:

---nameofsegment---

Anything between this line and either the end of the file or the next text segment defines the contents of that text segment.

For example, the following page has 2 segments: content and sidebar:

---
title: Some page with 2 text segments
layout: awesome_layout
---
This is the main text. It's formatted with **Markdown**
as usual (or whatever default formatter you use).

That's pretty much it.

---sidebar---
Now this is a text in the "sidebar" segment. It's also
formatted, but can be inserted in a completely different
place in the layout.

The same way you insert the main text in your layout using the content variable (e.g. {{ content|raw }} if you’re using the default Twig template engine), you can insert any other text segment in your layout by using the variable named after the segment (e.g. {{ sidebar|raw }}). For more information on template variables and layouts, see the templating documentation.

The default segment

The default segment (content) is always the first one, found right after the page configuration header. If for some reason you don’t want a default segment, just start a named segment immediately after the header like so:

---
title: Some weird page
---
---nameofsegment---
Text goes here...

Changing the formatter

When you start a new content segment, you can specify a different formatter to use with the following syntax:

---
title: Yet another example page
---
Blah blah, this is the main segment, using the default formatter which is probably Markdown.

And then...
---othersegment:textile---
%big. BLAM! TEXTILE!

Changing the formatter in the middle of a segment

You can also change the formatter in the middle of a segment with the following syntax:

So I'm writing text in Markdown when...

<--textile-->
%big. BLAM! TEXTILE AGAIN!

<--markdown-->
...and then I'm back to Markdown.