adamrenklint/asimovjs.org

title: Content
---
text:

The public content is defined by folders and textfiles in the <code>content</code> folder.

For example, to create a page at the url <code>/my-first-page</code>, first create the folder <code>content/my-first-page</code>. In this folder, create a textfile called <code>page.txt</code>. This file will contain the data for the page, and the name of the file defines which template will be used to render it.

In this case, the template <code>page.tmpl</code> found in <code>site/templates</code> will be rendered with the data from <code>page.txt</code> and made available at the url <code>/my-first-page</code>.

## Structure of a content page

A content page is just a text file with sections of data, separated by three dashes. Each section has a key, followed by a colon, and the value of the key.

    title: My very first post
    ---
    tags: blog, awesome
    ---
    text:
    Lorem ipsum, all that good stuff...

## Syntax and format

### Text

    ---
    title: My awesome title!
    ---

This one is pretty obvious, right?

### Lists

    ---
    tags: blog, awesome
    ---

A comma separated list, like the tags list in the example above, is turned into an array that is available inside templates as <code>page.tags</code> when rendering.

### Markdown

    ---
    text:
    ## Subheadline
    - First item
    ---

Just use {{link "https://daringfireball.net/projects/markdown" "Markdown" target="_blank"}} syntax in a content section, and it will be rendered as markdown.

### YAML

    title: Downloads
    ---
    stores:
      appstore: http://www.appstore.com
      chromewebstore: http://www.chromewebstore.com

Define nested data structures without breaking a sweat, using {{link "http://en.wikipedia.org/wiki/YAML" "YAML"}}, and iterate over the data in your templates and template helpers.

### Handlebars

    ---
    title: The url is {{page.url}}
    ---

Speaking of templates - every content section will be scanned for {{link "http://handlebarsjs.com/" "Handlebars"}} syntax, then compiled and rendered as a template. This means you can use any template helper that is available in the project from within the content file.

## Adding media

To add and use an image on one page, simply add it in the page's folder and use the template helper to include the image element. For example, load the image <code>1.png</code> by adding <code>&#123;&#123;image "1.png"&#125;&#125;</code> to the content file or the template used to render the content file.

A lot of times, several pages will need to share images. Put these resources in <code>site/images</code> and use them the same way as above, using only the filename - paths are automatically resolved.

## Order of pages

To ensure a specific order when iterating over the children of a url, simply prepend the folder name with a number and a dash. <code>/my-first-page</code> becomes <code>/01-my-first/page</code>. The number is however removed from the public url, which remains <code>/my-first-page</code>.

## Hidden urls (WIP)

Any folder name that starts with an underscore, for example <code>/_private-stuff</code>, defines a hidden folder and any request to this folder or any of its children will be blocked.

## Inheritance (WIP)

Sometimes, a set of pages need share the same properties, or new page might even be considered an extension of an existing page. Recursive inheritance with deeply merged properties can be enabled with one line in your content text file, defining the url of the page node to inherit from.

    ...
    inherits: /blog/first-post
    ...

If you want to inherit from a language other than the default one, just add the language code to the url. For example <code>inherits: /blog/first-post/de<code>.

If you have a partially translated page, you can let it inherit from the default language page to fill in the blanks.

And remember, the <code>inherits</code> content section is just like any other, meaning you can use template syntax to use page variables, like the url or title, to define what path to inherit from.