Statocles::Help::Config - A guide to configuring a Statocles site
version 0.086
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.
statocles create
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.
ATTRIBUTES
The configuration file is, by default, called site.yml. See the statocles command documentation if you want to have multiple site configuration files.
site.yml
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.
blog
$ 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.
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 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).
/blog
/
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.
gh-pages
# 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.
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 Statocles::Help::Theme for information on how to change and customize your theme.
default
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.
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 /.
index
url_root
Finally, we can define a nav list, again giving a name: main. The default template uses the main nav across the top.
nav
main
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.
statocles
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.
In addition to our blog app, we also want to add some plain Markdown content, and some images.
For basic pages with no structure or extras, there is the basic app: Statocles::App::Basic. The basic 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. The basic app also takes any other files (HTML, images, audio, video, and other formats) and copies them into the deployed site..
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 basic_app: class: Statocles::App::Basic args: url_root: '/' store: '.'
To enable the new app, we just need to add it to the site's apps.
apps
# site.yml site: class: Statocles::Site args: apps: blog: $ref: blog_app basic: $ref: basic_app deploy: $ref: github_deploy title: My Site index: /blog nav: main: - title: Blog href: /
Now, we just need some content for our basic app to deploy. The basic 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:
about.markdown
--- title: About --- # About Me This is a personal website!
Then, run statocles daemon to test the new page.
statocles daemon
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 basic: $ref: basic_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.
statocles build
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' basic_app: class: Statocles::App::Basic args: url_root: '/' store: '.' github_deploy: class: Statocles::Deploy::Git args: branch: gh-pages site: class: Statocles::Site args: apps: blog: $ref: blog_app basic: $ref: basic_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.
statocles deploy
There are special features built-in to all default themes that can be enabled by adding the appropriate configuration to the site object or app objects.
To add a shortcut icon to your site, place the image file anywhere that will be deployed (if you're using the configuration above, you can put it in the root). Then, add an icon property to the images key of the site object, like so:
icon
images
site
site: class: Statocles::Site args: images: icon: src: /favicon.png
For more information, see the images attribute documentation.
You can easily add extra scripts and stylesheets by adding them to the site's links attribute:
links
site: class: Statocles::Site args: links: stylesheet: - href: /css/site.css script: - href: /js/site.js
Create the files /css/site.css and /js/site.js and they will be picked up by the basic_app we created, above. If you accidentally create a link to a file that doesn't exist, Statocles will warn you.
/css/site.css
/js/site.js
basic_app
There are third-party services that can be integrated into your site by adding keys to the data configuration section.
data
Disqus is a free, hosted comment system that can be easily added to static sites to provide some user interaction.
To add Disqus comments to your blog, add your Disqus shortname (from http://YOUR_NAME.disqus.com/admin) to the site data, like so:
http://YOUR_NAME.disqus.com/admin
# site.yml site: class: Statocles::Site args: # ... data: disqus: shortname: 'YOUR_NAME'
This will add a comments section to the bottom of your blog posts, and show the number of comments in the blog list pages.
What is a short name?
Sign up for Disqus
The configuration file is a Beam::Wire container. This means that any object attributes (in the ATTRIBUTES section of their documentation) can be set from the config file.
Additional functionality can be added by plugins using the site's plugins attribute:
plugins
# site.yml site: class: Statocles::Site args: # ... plugins: highlight: $class: Statocles::Plugin::Highlight $args: theme: solarized-light
Each plugin has a name (highlight), and requires a $class (the class name of the plugin) and optional $args (the plugin's attributes).
highlight
$class
$args
See the list of bundled plugins.
To use a custom Markdown parser, like Text::MultiMarkdown, which has some extra syntax features, you can use the site object's markdown attribute to configure a custom object with $class and optional $args:
markdown
# site.yml site: class: Statocles::Site args: # ... markdown: $class: Text::MultiMarkdown $args: use_metadata: false
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.