NAME

Statocles::App::Blog - A blog application

DESCRIPTION

This is a simple blog application for Statocles.

FEATURES

Content dividers. By dividing your main content with "---", you create sections. Only the first section will show up on the index page or in RSS feeds.
RSS and Atom syndication feeds.
Tags to organize blog posts. Tags have their own custom feeds so users can subscribe to only those posts they care about.
Cross-post links to redirect users to a syndicated blog. Useful when you participate in many blogs and want to drive traffic to them.
Post-dated blog posts to appear automatically when the date is passed. If a blog post is set in the future, it will not be added to the site when running build or deploy.

In order to ensure that post-dated blogs get added, you may want to run deploy in a nightly cron job.

ATTRIBUTES

store

    # site.yml
    blog:
        class: Statocles::App::Blog
        args:
            store: _posts

The store directory path to read for blog posts. Required.

The Blog directory is organized in a tree by date, with a directory for the year, month, day, and post. Each blog post is its own directory to allow for additional files for the post, like images or additional pages.

tag_text

    # site.yml
    blog:
        class: Statocles::App::Blog
        args:
            tag_text:
                software: Posts about software and development
                travel: My travelogue around the world!

A hash of tag and introductory Markdown that will be shown on the tag's main page. Having a description is optional.

Using Beam::Wire's $config directive, you can put the tag text in an external file:

    # site.yml
    blog:
        class: Statocles::App::Blog
        args:
            tag_text:
                $config: tags.yml

    # tags.yml
    software: |-
        # Software

        Posts about software development, mostly in [Perl](http://perl.org)

    travel: |-
        # Travel

        My travelogue around the world! [Also visit my Instagram!](http://example.com)

page_size

    # site.yml
    blog:
        class: Statocles::App::Blog
        args:
            page_size: 5

The number of posts to put in a page (the main page and the tag pages). Defaults to 5.

index_tags

    # site.yml
    blog:
        class: Statocles::App::Blog
        args:
            index_tags: [ '-private', '+important' ]

Filter the tags shown in the index page. An array of tags prefixed with either a + or a -. By prefixing the tag with a "-", it will be removed from the index, unless a later tag prefixed with a "+" also matches.

By default, all tags are shown on the index page.

So, given a document with tags "foo", and "bar":

    index_tags: [ ]                 # document will be included
    index_tags: [ '-foo' ]          # document will not be included
    index_tags: [ '-foo', '+bar' ]  # document will be included

template_dir

The directory (inside the theme directory) to use for this app's templates. Defaults to blog.

METHODS

command

    my $exitval = $app->command( $app_name, @args );

Run a command on this app. The app name is used to build the help, so users get exactly what they need to run.

make_slug

    my $slug = $app->make_slug( $title );

Given a post title, remove special characters to create a slug.

index

    my @pages = $app->index( \@post_pages );

Build the index page (a list page) and all related feed pages out of the given array reference of post pages.

tag_pages

    my @pages = $app->tag_pages( \%tag_pages );

Get pages for the tags in the given blog post documents (build from the post_pages method, including relevant feed pages.

pages

    my @pages = $app->pages( %options );

Get all the pages for this application. Available options are:

date: The date to build for. Only posts on or before this date will be built. Defaults to the current date.

recent_posts

    my @pages = $app->recent_posts( $count, %filter );

Get the last $count recent posts for this blog. Useful for templates and site index pages.

%filter is an optional set of filters to apply to only show recent posts matching the given criteria. The following filters are available:

tags: (string) Only show posts with the given tag

page_url

    my $url = $app->page_url( $page )

Return the absolute URL to this page object, removing the "/index.html" if necessary.

COMMANDS

post

    post [--date <date>] <title>

Create a new blog post, optionally setting an initial title. The post will be created in a directory according to the current date.

Initial post content can be read from STDIN. This lets you write other programs to generate content for blog posts (for example, to help automate release blog posts).

THEME

index.html

The index page template. Gets the following template variables:

site

The Statocles::Site object.

pages

An array reference containing all the blog post pages. Each page is a hash reference with the following keys:

content: The post content
title: The post title
author: The post author

post.html

The main post page template. Gets the following template variables:

site: The Statocles::Site object
content: The post content
title: The post title
author: The post author