- Building site.yml - The Main Configuration File
- The statocles Command
- Adding More Apps
- DEFAULT THEME FEATURES
- ADVANCED CONFIGURATION
- SEE ALSO
- COPYRIGHT AND LICENSE
Statocles::Help::Config - A guide to configuring a Statocles site
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 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.
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
$ 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
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
# 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.
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
index attribute gives the path to the page to use as our index page. Since the blog's
/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.
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.
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
# 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:
--- title: About --- # About Me This is a personal website!
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 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.
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
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:
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
site: class: Statocles::Site args: links: stylesheet: - href: /css/site.css script: - href: /js/site.js
Create the files
/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.
There are third-party services that can be integrated into your site by adding keys to the
data configuration section.
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:
# 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.
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
# 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).
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
# site.yml site: class: Statocles::Site args: # ... markdown: $class: Text::MultiMarkdown $args: use_metadata: false
- Statocles::Help::Error - How to fix error messages from Statocles
- Statocles::Help::Content - How to edit content with Statocles
- Statocles::Help::Deploy - How to deploy a Statocles site
- Statocles::Help::Theme - How to customize a Statocles theme
Doug Bell <firstname.lastname@example.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.