# PODNAME: Statocles::Help::Content
# ABSTRACT: How to use Statocles to write content

=head1 DESCRIPTION

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

=head1 BASIC CONTENT

=head2 Run an App Command

Every application in a Statocles site has a name. The name is the key in the
L<site object's|Statocles::Site> C<apps> attribute in the L<site.yml config
file|Statocles::Help::Config>. We can use that name to access the app's
command-line commands.

Not all applications have or need commands. See L<the application
documentation|Statocles::App/"SEE ALSO"> for more information.

=head3 Create a Blog Post

To create a new blog post using L<the blog app|Statocles::App::Blog>, we can
use the C<post> command:

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

Everything after C<post> will be used as the title of the post.

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

=head3 Create a Page

To create a page using L<the basic app|Statocles::App::Basic>, 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

=head2 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 L<Statocles::Document
attributes documentation|Statocles::Document/ATTRIBUTES>.

=head2 Markdown

Below the frontmatter, after the second C<--->, everything is
L<Markdown|http://daringfireball.net/projects/markdown/syntax>, 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 L<the Markdown
website|http://daringfireball.net/projects/markdown/syntax> for full
documentation on Markdown syntax.

=head2 Build The Site

    $ statocles build

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

=head2 Test The Site

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

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

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

=head2 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.

=head2 Deploy The Site

    $ statocles deploy

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

=head1 ADVANCED FEATURES

Most of the content in a Statocles site consists of
L<documents|Statocles::Document>.  This section explains some of the options
available when writing documents.

=head2 Content Sections

After the frontmatter, you can use C<---> to divide the document into sections.
This may have meaning for an app. For example, L<the blog
app|Statocles::App::Blog> 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!

=head2 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 C<template> or C<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 C<document/recipe.html.ep> template will be read from
the L<theme directory|Statocles::Help::Theme>.

=head2 Generated Content

All documents are also run through L<the template
processor|Statocles::Help::Theme/Writing-a-Template>, so we have access to
L<template helpers|Statocles::Help::Theme/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:

=over 4

=item C<$self> - The current L<document object|Statocles::Document>

=item C<$site> - The current L<site object|Statocles::Site>

=item C<$app> - The current L<app object|Statocles::App>

=back

=head2 Helper Functions

Like the L<theme's templates|Statocles::Help::Theme>, the document has
access to the theme's helper functions, like L<the Highlight
plugin|Statocles::Plugin::Highlight>:

    ---
    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 L<add the plugin to your
configuration|Statocles::Help::Config/Plugins>!

=head1 SEE ALSO

=over 4

=item L<Statocles::Document>

These objects are created from document files.

=back