Content Editing
Each folder which is to be displayed as a page should have a .yml file inside it (even if this file is empty). The name of the .yml file should match up with a file in the /templates folder, as this is how Stacey knows which template to use for each page.
-
Browser hits
http://yourdomain.com/?/about/. -
Stacey reads the appropriate content file
/content/3.about/content.yml.title: About Title content: | Lorem ipsum.
-
Two variables are extracted from the keys & values from within the
.ymlfile:page.title&page.content. These will be available for use within the templates. -
Stacey finds the matching template file, in this case,
/templates/content.html -
Stacey replaces the variables in the template and outputs the final html.
So this template code:
<section class="main">
<header>{{ page.title }}</header>
<p>{{ page.content }}</p>
</section>becomes this html:
<section class="main">
<header>About Title</header>
<p>Lorem ipsum.</p>
</section>The content files all follow a standard format; each key is followed by a : and then your value.
key: valueThe keys match up with variable markers in the template files which get replaced with the contents of the value. You can create as many of your own keys as you need.
A standard content file looks something like this:
title: The Test Project 1
date: 2009, June
content: |
Lorem ipsum dolor...The above examples are only the simplest usage of YAML, the format itself is very powerful, so it is worth reading more about its capabilities.
The YAML cookbook for Ruby gives an nice overview of the possibilities that YAML affords (although the example outputs are all written as ruby).
Additionally, the path variable is exposed to your content files, which is useful for linking to assets within the current folder.
It will output the relative path to the containing folder of the current page.
ie. ../content/4.projects/10.project-1/
Standard usage, looks something like this:
content: |
An example image, which sits in the same folder as this YAML file: <img src="{{ path }}/image01.jpg">
To bypass the cache for a specific page, you can add bypass_cache: true to its text file. Any requests to this page will no longer be cached. This is useful for pages which use randomised variables, php code or are secured with password_protect.
To use Markdown formatting, your value should be followed by a pipe (|) symbol, a newline and then the following value should be indented by two spaces.
Within the following example, date will come through as plain text, while content will be parsed as Markdown.
This:
date: 2009, June
content: |
## A Title
First content paragraph.
Second content paragraph.will become:
page.date => 2009, June
page.content => <h2>A Title</h2> <p>First content paragraph.</p> <p>Second content paragraph.</p>
Because Markdown ignores html, if you prefer, you can use standard markup in place of Markdown. The keys & values mentioned above could just as easily be written out as:
date: 2009, June
content: |
<h2>A Title</h2>
<p>First content paragraph.</p>
<p>Second content paragraph.</p>Stacey uses PHP Markdown Extra which is a php-specific version of Markdown. It also adds some of its own functionality, such as fenced code blocks and header ids, so you should refer to its documentation as well as that of the original Markdown.
All of your .yml files should be encoded using UTF-8. In addition to ensuring no strange characters are inserted which could break stacey’s rendering engine, this will also allow you to use special characters such as ö, — or double-byte characters such as 照 or ラ.
Any decent text editor will give you the option to edit and save your YAML files as UTF-8, so google should be able to provide answers on how to do this with your editor of choice.