NAME

Statocles::Help::Content - How to use Statocles to write content

DESCRIPTION

This guide describes how to use the statocles command to manage site content, build, test, and deploy the site.

BASIC CONTENT

Run an App Command

Every application in a Statocles site has a name. The name is the key in the site object's apps attribute in the site.yml config file. We can use that name to access the app's command-line commands.

Not all applications have or need commands. See the application documentation for more information.

Create a Blog Post

To create a new blog post using the blog app, we can use the post command:

    $ statocles blog post Snickerdoodles
    New post at: blog/2014/06/04/snickerdoodles

Everything after post will be used as the title of the post.

If you have the EDITOR environment variable set, your editor will automatically open on the newly-created document.

Create a Page

To create a page using the basic app, we just have to create a new file:

    ### Create /page/index.html
    $ vim page/index.markdown

    ### Create /page/about/index.html
    $ mkdir page/about
    $ vim page/about/index.markdown

    ### Create /page/resume.html
    $ vim page/resume.markdown

Frontmatter

Statocles documents start out with a block of YAML, called the frontmatter. This header holds metadata about the document, such as the title, author, date, tags, and other information.

    ---
    title: Snickerdoodles
    author: preaction
    tags: cookies, cinnamon
    ---

Frontmatter is optional, but it's recommended that you have at least a title. Available frontmatter options are listed in the Statocles::Document attributes documentation.

Markdown

Below the frontmatter, after the second ---, everything is Markdown, a simple, text-based language that will be generated into HTML.

    # Snickerdoodles

    Snickerdoodles are a simple, chewy, cinnamon cookie.

    ## Ingredients

    * 1/2 c butter
    * 1 c sugar

This will be parsed into

    <h1>Snickerdoodles</h1>

    <p>Snickerdoodles are a simple, chewy, cinnamon cookie.</p>

    <h2>Ingredients</h2>

    <ul>
        <li>1/2 c butter</li>
        <li>1 c sugar</li>
    </ul>

Markdown has some simple formatting for basic things. For more advanced needs, you can embed raw HTML directly. See the Markdown website for full documentation on Markdown syntax.

Build The Site

    $ statocles build

Running the build command will write all our pages to the .statocles-build directory. We can open up this directory and look at the files to make sure that our deploy will be correct.

Test The Site

    $ statocles daemon
    Listening on http://*:3000

Run the daemon command to start an HTTP server to view your built site. This will automatically build the site, so if you forgot to run build, don't worry.

If you edit any content, running build again will update the site. On Mac OS X, editing any content will automatically rebuild the site.

Commit Your Changes

    $ git add blog/2014/06/04/my-first-post.markdown
    $ git commit -m'My first post'

Once the build looks good, we'll want to commit our changes. The major feature of having a website in a git repository is change tracking.

Deploy The Site

    $ statocles deploy

Running the deploy command will, in the case of the Git deploy, commit the updated pages to the Git repository. deploy will try to do a git push automatically, so your changes are now live on Github Pages!

ADVANCED FEATURES

Most of the content in a Statocles site consists of documents. This section explains some of the options available when writing documents.

Content Sections

After the frontmatter, you can use --- to divide the document into sections. This may have meaning for an app. For example, the blog app shows only the first content section on the index page, tag pages, and feeds, hiding the rest of the post behind a "Continue reading" link.

    ---
    title: My Long Post
    ---

    # A Long Post

    This is a long post. Since I don't want you to have to skip past all the content,
    I will instead put a "Read more" link below.

    ---

    Turns out this isn't that long of a post. Made you click!

Custom Template and Layout

Every document can have its own custom template and layout. This allows you to have multiple kinds of posts in a blog, or additional customization for particular pages.

You can specify a custom template or layout by using the template or layout key in the frontmatter:

    ---
    title: Chocolate-Chip Cookies
    template: document/recipe.html
    ---

    # Chocolate-Chip Cookies

    This is really the best cookie ever!

When the page is created, the document/recipe.html.ep template will be read from the theme directory.

Generated Content

All documents are also run through the template processor, so we have access to template helpers, but we can also generate our content from the document's frontmatter data.

    ---
    title: Cheddar Cheese Sauce
    data:
        ingredients:
            - 1 tbsp flour
            - 1 tbsp butter
            - 1 c milk
            - 2 c cheddar cheese
    ---

    % for my $ingredient ( @{ $self->data->{ingredients} } ) {
    * <%= $ingredient %></li>
    % }

Since this template is generated before the Markdown is parsed, you can generate HTML or Markdown from your template.

When the content is being generated, you have access to the following variables:

$self - The current document object
$site - The current site object
$app - The current app object

Helper Functions

Like the theme's templates, the document has access to the theme's helper functions, like the Highlight plugin:

    ---
    title: How to use Perl
    ---

    Here is the basic `Hello, World!` in Perl:

    %= highlight Perl => begin
    print "Hello, World!\n";
    % end

Don't forget to add the plugin to your configuration!