NAME
Statocles::Help::Setup - A guide to setting up a new Statocles site
VERSION
version 0.034
DESCRIPTION
This document describes how to set up a simple blog web site suitable to be deployed to GitHub Pages using Statocles.
Building site.yml - The Main Configuration File
Statocles uses Beam::Wire, a dependency-injection module, for configuration. The format is YAML and contains the data needed to build the objects: Arguments to the object's constructor. This means that any ATTRIBUTES
defined in the documentation can be used in the configuration file.
The configuration file is, by default, called site.yml
. See the statocles command documentation if you want to have multiple site configuration files.
A Source
Statocles takes simple, YAML-and-Markdown-formatted document files and builds HTML pages out of them.
So we need a place to put our source documents. A store fills multiple roles relating to reading and writing files. Right now, we need it to hold on to our blog posts. We'll put our blog posts in the blog
directory.
The blog application will use this store to add new blog posts and build web pages from the documents in the blog
directory. More on that later.
An App
A Statocles app is the driver that turns documents into pages. To build pages, we need a store full of documents. We define our store with the string blog
, which will get magically coerced into a file store object.
Since we're building a blog site, we'll use the Statocles blog app:
blog_app:
class: Statocles::App::Blog
args:
url_root: /blog
store: 'blog'
We put our blog app under the root URL /blog
. All pages that come from this app will start with /blog
(except the index page, we'll move that to /index.html
, later).
Destinations
Before we can generate pages, we need a place to put them. Statocles needs two places, a build directory (a staging area), and a deploy object (the final destination for the site).
For our site, we will make a build
directory for our staging area, where we can verify that our site looks correct before we deploy.
Make sure this directory exists:
$ mkdir build
For our destination, we need to build a deploy object for Git repositories using Statocles::Deploy::Git. Our deploy object will copy files from the build
directory into the Git repository. Our deploy will happen in the root directory of our site (.
). This is good for a GitHub Pages site.
github_deploy:
class: Statocles::Deploy::Git
args:
path: .
branch: gh-pages
Though we are going to deploy to Git, we could also deploy to SFTP or FTP or transfer the pages to a CDN.
A Theme
Last thing we need before we can build our site is a theme. A theme (Statocles::Theme) builds and parses templates into Statocles::Template objects. We'll use the Statocles default theme, included with the module. The special ::default
string will look in the Statocles share/theme
directory.
A Site
Now that we're ready, we can tie it all together. A site is a collection of apps that build and deploy to the same place. The special git site knows how to deploy to git repositories.
site:
class: Statocles::Site
args:
theme: '::default'
apps:
blog:
$ref: blog_app
build_store: 'build'
deploy:
$ref: github_deploy
title: My Site
index: blog
nav:
main:
- title: Blog
href: /index.html
We define our theme with the string ::default
, which will get magically coerced into a theme object.
When adding apps to our site, we give them a name (in this case blog
) so that we can refer to them on the command-line (later).
Just like the blog store, the build_store
will magically create a Statocles::Store::File object from the path string.
As part of the default template, we can provide a site title
.
The index
attribute gives the name of the app to use as our index page. Since we only have one app, we can only give it the blog
. Whatever main page the blog app defines will be moved to the main site index /index.html
.
Finally, we can define a nav
list, again giving a name: main
. The default template uses the main
nav across the top.
The Complete site.yml
Combine it all together and you get this. Feel free to copy and paste to start your own site.
blog_app:
class: Statocles::App::Blog
args:
url_root: /blog
store: 'blog'
github_deploy:
class: Statocles::Deploy::Git
args:
path: .
branch: gh-pages
site:
class: Statocles::Site
args:
theme: '::default'
apps:
blog:
$ref: blog_app
build_store: 'build'
deploy:
$ref: github_deploy
title: My Site
index: blog
nav:
main:
- title: Blog
href: /index.html
NOTE: One of the most useful things about using a dependency injection module is that you can easily plug-in your own classes. If you want to use your own template format, you can build your own Statocles::Theme class that provides a different kind of Statocles::Template object and use that instead. If you want to use your own document format, you can make your own Statocles::Store class that reads from a database.
The statocles
Command
Now that we have a site.yml
, we can run the statocles command to manage our site.
Initialize Your Git Repo
$ git init
$ git remote add origin ssh://git@github.com/preaction/preaction.github.io
Before we can get going, we need to create our git repository.
NOTE: In the future I plan to include this as a statocles create
command.
Create A Blog Post
Remember when we gave our blog app a name? Now we can use that name to access the blog's command-line commands. To create a new blog post, we can use the post
command:
$ statocles blog post My First Post
New post at: blog/2014/06/04/my-first-post.markdown
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.
Build The Site
$ statocles build
Running the build
command will write all our pages to the build
store, which points to the 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!
Adding More Apps
In addition to our blog app, we also want to add some plain Markdown content, and some images.
Plain Markdown
For plain markdown, there is the plain app: Statocles::App::Plain. The plain app takes the same YAML-and-Markdown-formatted documents as the blog app and creates HTML pages, without the lists, tags, and feeds the blog generates.
Like the blog, we need a store to find our documents. This time, we'll use the root directory of our repository, .
. Finally, we'll need a URL root. Since we're using the root directory for our documents, we'll use the root URL for our destination /
.
plain_app:
class: Statocles::App::Plain
args:
url_root: '/'
store: '.'
Now we just need to add this app to our site, but before we do, we'll create an app for our static files.
Static Files
Lastly, we wanted a place to put any file at all. No processing. No templates. Just a simple copy from one store to another. For this one, we'll put everything in the /static
directory, and give a URL root to match.
static_app:
class: Statocles::App::Static
args:
url_root: '/static'
store: 'static'
Add the New Apps
To enable the new apps, we just need to add them to the site's apps
.
site:
class: Statocles::Site::Git
args:
apps:
blog:
$ref: blog_app
plain:
$ref: plain_app
static:
$ref: static_app
Add Plain Content
Now, we just need some content for our plain app to deploy. The plain app uses the same format as the blog, so we need a YAML header followed by some Markdown content:
Create a file named about.markdown
with the following content:
---
title: About
---
# About Me
This is a personal website!
Then, run statocles build
. The about.markdown
turns into about.html
in our build/
directory.
Now we should probably make a link in our main nav to the new about page:
site:
class: Statocles::Site::Git
args:
# ... [redacted]
nav:
main:
- title: Blog
href: /index.html
- title: About
href: /about.html
Now, if we run statocles build
again, we can see the link in our header.
The Complete site.yml - With More Apps
Along with the blog app and our other settings, here is our new, complete site.yml:
blog_app:
class: Statocles::App::Blog
args:
url_root: /blog
store: 'blog'
plain_app:
class: Statocles::App::Plain
args:
url_root: '/'
store: '.'
static_app:
github_deploy:
class: Statocles::Deploy::Git
args:
path: .
branch: gh-pages
site:
class: Statocles::Site::Git
args:
theme: '::default'
apps:
blog:
$ref: blog_app
plain:
$ref: plain_app
static:
$ref: static_app
build_store: 'build'
deploy:
$ref: github_deploy
title: My Site
index: blog
nav:
main:
- title: Blog
href: /index.html
- title: About
href: /about.html
If we're satisfied with our new About page, we can deploy our site with statocles deploy
.
AUTHOR
Doug Bell <preaction@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2015 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.