Statocles::Help::Content - How to use Statocles to write content
version 0.075
This guide describes how to use the statocles command to manage site content, build, test, and deploy the site.
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.
apps
Not all applications have or need commands. See the application documentation for more information.
To create a new blog post using the blog app, we can use the post command:
post
$ 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.
EDITOR
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
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.
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.
$ 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.
build
.statocles-build
$ 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.
daemon
If you edit any content, running build again will update the site. On Mac OS X, editing any content will automatically rebuild the site.
$ 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.
$ 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!
deploy
git push
Most of the content in a Statocles site consists of documents. This section explains some of the options available when writing documents.
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!
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:
template
layout
--- 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.
document/recipe.html.ep
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
$site
$app
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!
These objects are created from document files.
Doug Bell <preaction@cpan.org>
This software is copyright (c) 2016 by Doug Bell.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Statocles, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Statocles
CPAN shell
perl -MCPAN -e shell install Statocles
For more information on module installation, please visit the detailed CPAN module installation guide.