Back to documentation
# 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 Plain Page
To creat a plain page using L<the plain app|Statocles::App::Plain>, 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|Statocle::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
=head1 SEE ALSO
=over 4
=item L<Statocles::Document>
These objects are created from document files.
=back
