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 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 Statocles::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.

Basic Pages

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: '.'

Add the New Apps

To enable the new app, we just need to add it to the site's 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: /

Add Basic Content

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!

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
                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.

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'

    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.

DEFAULT THEME FEATURES

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.

Shortcut Icons

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.

Additional Stylesheets and Scripts

You can easily add extra scripts and stylesheets by adding them to the site's links attribute:

    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.

Service Integration

There are third-party services that can be integrated into your site by adding keys to the data configuration section.

Disqus

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.

ADVANCED CONFIGURATION

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.

Plugins

Additional functionality can be added by plugins using the site's plugins attribute:

    # 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).

See the list of bundled plugins.

Custom Markdown

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:

    # site.yml
    site:
        class: Statocles::Site
        args:
            # ...
            markdown:
                $class: Text::MultiMarkdown
                $args:
                    use_metadata: false