Documentation

  1. Overview
  2. Creating Pages
    1. Editing Content
  3. Editing Templates
    1. Templating Language
    2. Assets
  4. Variable Types
    1. @variables
    2. $collections
    3. :partials
  5. RSS/Atom/JSON
  6. Download
    Stacey v2.3.0
  7. News & Updates
  8. Support
Stacey

Content Editing

Within the /content directory, there is a file named _shared.txt.

If you open it up with a text editor, you should see:

name: Name
-
profession: Graphic Designer
-
email: hi@yourdomain.com

Replace the highlighted data with your own details.

Text file encoding

All of your .txt 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 text files as UTF-8, so google should be able to provide answers on how to do this with your editor of choice.

You can read more about text files & UTF-8 encoding on Wikipedia.

Editing content

Each folder which is to be displayed as a page should have a .txt file inside it (even if this text file is empty). The name of the .txt file should match up with a file in the /templates folder, as this is how stacey knows which template to use for each page. Screenshot of /content folder with 'project.txt' selected Screenshot of /templates folder with 'project.html' selected

How variables are created:

  1. Browser hits http://yourdomain.com/?/about/.
  2. Stacey reads the appropriate content file /content/3.about/content.txt.

    title: About Title
    -
    content: 
    Lorem ipsum.
    
  3. Two variables are extracted from the keys & values from within the .txt file: @title & @content. These will be available for use within the templates.
  4. Stacey finds the matching template file, in this case, /templates/content.html
  5. Stacey replaces the variables in the template and outputs the final html.

    So this template code:

    <div id="main">
      <h1>@title</h1>
      @content
    </div>
    

    becomes this html:

    <div id="main">
      <h1>About Title</h1>
      <p>Lorem ipsum.</p>
    </div>
    

Content file format

The content files all follow a standard format; each key is followed by a :, a value and a hyphen (-) to close the value.

key: value 
-

The 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.

Keys

A key may only contain the following characters: abcdefghijklmnopqrstuvwxyz0123456789_

Essentially, lowercase latin alphanumeric characters and underscores.
Or, for the more technically inclined, anything which can be matched by the following regular expression: /[a-z0-9_]+?:/

A standard content file looks something like this:

title: The Test Project 1
-
date: 2009, Jun—
-
content: 
Lorem ipsum dolor...

Separating Keys & Values

Each value should be followed by a line containing only a hyphen character (although the parser is forgiving of any accidental tabs or spaces).

The hyphen is optional on the last key/value pair.

title:  The Test Project 1
-
date: ...

Empty Values

If you want one of the values to be empty, leave a space after the colon.

title: 
-
date: ...

@path

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/

@bypass_cache

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 or php code.

Markdown

Any values which contain one or more newline characters (line-breaks) will be parsed as Markdown.

Within the following example, @title will come through as plain text, while @content will be parsed as Markdown.

This:

date: 2009, Jun—
-
content:
# Title
Lorem ipsum.

will become:

@date => 2009, Jun—

@content => <h1>Title</h1> <p>Lorem ipsum.</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, Jun—
-
content:
<h1>Title</h1>
<p>Lorem ipsum.</p>

Markdown References

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.