NAME
Statocles::Help::Config - A guide to configuring a Statocles site
DESCRIPTION
This document describes how to set up a simple blog web site suitable to be deployed to GitHub Pages using Statocles.
This document explains how to build a configuration file without using the statocles create
command.
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.
$ mkdir blog
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:
# site.yml
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 /
, later).
A Deploy
To deploy our site to Github, we need to build a deploy object for Git repositories using Statocles::Deploy::Git. Our deploy object will copy our built pages into the Git repository and commit them. Our deploy will happen in the root directory of our site on the gh-pages
branch.
# site.yml
github_deploy:
class: Statocles::Deploy::Git
args:
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. See Statocles::Help::Deploy for more information.
A Theme
We could set up a theme (Statocles::Theme) to change how our site looks, but for now, we'll use the default
theme included with Statocles. See Statocle::Help::Theme for information on how to change and customize your theme.
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.
# site.yml
site:
class: Statocles::Site
args:
apps:
blog:
$ref: blog_app
deploy:
$ref: github_deploy
title: My Site
index: /blog
nav:
main:
- title: Blog
href: /
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).
As part of the default template, we can provide a site title
.
The index
attribute gives the path to the page to use as our index page. Since the blog's url_root
is /blog
, this will move the main blog page to the main site index /
.
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.
# site.yml
blog_app:
class: Statocles::App::Blog
args:
url_root: /blog
store: 'blog'
github_deploy:
class: Statocles::Deploy::Git
args:
branch: gh-pages
site:
class: Statocles::Site
args:
apps:
blog:
$ref: blog_app
deploy:
$ref: github_deploy
title: My Site
index: /blog
nav:
main:
- title: Blog
href: /
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.
See Statocles::Help::Content for more information about editing the site's content.
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 /
.
# site.yml
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.
# site.yml
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.yml
site:
class: Statocles::Site
args:
apps:
blog:
$ref: blog_app
plain:
$ref: plain_app
static:
$ref: static_app
deploy:
$ref: github_deploy
title: My Site
index: /blog
nav:
main:
- title: Blog
href: /
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 daemon
to test the new page.
Now we should probably make a link in our main nav to the new about page:
# site.yml
site:
class: Statocles::Site
args:
apps:
blog:
$ref: blog_app
plain:
$ref: plain_app
static:
$ref: static_app
deploy:
$ref: github_deploy
title: My Site
index: /blog
nav:
main:
- title: Blog
href: /
- 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:
# 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:
class: Statocles::App::Static
args:
url_root: '/static'
store: 'static'
github_deploy:
class: Statocles::Deploy::Git
args:
branch: gh-pages
site:
class: Statocles::Site
args:
apps:
blog:
$ref: blog_app
plain:
$ref: plain_app
static:
$ref: static_app
deploy:
$ref: github_deploy
title: My Site
index: /blog
nav:
main:
- title: Blog
href: /
- title: About
href: /about.html
If we're satisfied with our new About page, we can deploy our site with statocles deploy
.