- site.yml - The Main Configuration File
- The statocles Command
- COPYRIGHT AND LICENSE
Statocles::Help::Setup - A guide to setting up a new Statocles site
This document describes how to set up a simple blog web site suitable to be deployed to GitHub Pages using Statocles.
Statocles uses Beam::Wire, a dependency-injection module, to define its 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.
theme: class: Statocles::Theme args: source_dir: '::default'
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.
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_store: class: Statocles::Store args: path: 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.
Though stores are usually just directories, they could also be a database, getting the blog post documents from a document database.
Since we're building a blog site, we'll use the Statocles blog app:
blog_app: class: Statocles::App::Blog args: url_root: /blog theme: $ref: theme source: $ref: blog_store
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). We used our already-defined
blog_store objects to fill in the required
source application attributes (
$ref is a Beam::Wire special instruction that says "look up this object from the config file").
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 directory (the final destination for the site).
build: class: Statocles::Store args: path: build deploy: class: Statocles::Store args: path: .
For our site, we've got a
build directory for our staging area, where we can verify that our site looks correct before we deploy. Our deploy will happen in the root directory of our site. This is good for a GitHub Pages site.
Though stores are usually just directories, they could also perform an SFTP or FTP or transfer the pages to a CDN (I think I have some evolution to do here).
site: class: Statocles::Site::Git args: apps: blog: $ref: blog_app build_store: $ref: build deploy_store: $ref: deploy deploy_branch: master title: My Site index: blog nav: main: - title: Blog href: /index.html
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). We add our
deploy_store. The git branch we want to deploy to is
master. As part of the default template, we can provide a site
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
Finally, we can define a
nav list, again giving a name:
main. The default template uses the
main nav across the top.
Combine it all together and you get this. Feel free to copy and paste to start your own site.
theme: class: Statocles::Theme args: source_dir: '::default' blog_store: class: Statocles::Store args: path: blog blog_app: class: Statocles::App::Blog args: url_root: /blog theme: $ref: theme source: $ref: blog_store build: class: Statocles::Store args: path: build deploy: class: Statocles::Store args: path: . site: class: Statocles::Site::Git args: apps: blog: $ref: blog_app build_store: $ref: build deploy_store: $ref: deploy title: My Site index: blog nav: main: - title: Blog href: /index.html
Now that we have a
site.yml, we can run the statocles command to manage our site.
$ git init $ git remote add origin ssh://email@example.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.
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
$ statocles blog post My First Post New post at: blog/2014/06/04/my-first-post.yml
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.
$ statocles build
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.
NOTE: In the future, you'll be able to run a local web server to navigate your site, but that's not yet available.
$ git add blog/2014/06/04/my-first-post.yml $ 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
deploy command will, in the case of the git site, 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!
Doug Bell <firstname.lastname@example.org>
This software is copyright (c) 2014 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.