Static Blog

A simple command-line utility for generating static blogs.

Building

This software requires Maven 1.3 or greater, Java 1.7 or greater, and Pandoc 1.17 or greater.

This project depends on the following:

• Dependency Bundles
• Utilities

Download and build these projects before building this software.

Building is as simple as mvn clean install

Installing

In the BlogDist folder, you will find a file called target/BlogDist-1.0.0-dist/ containing a script called blog and a JAR file blog.jar. Copy both files to a location on your PATH.

Creating a skelleton project

To create a skelleton project, cd into an empty directory and run blog -init or blog -i. If the directory already contains files, you will need to run blog -init --force.

Folder Structure

Your website should be laid out with the following directories:

• MyBlog/ - or whatever you want to call the root directory
  • src/
    • data/
      • config.yml
      • site.yml
      • authors.yml
    • posts/
      • drafts/ - posts that aren't ready yet
      • published/ - posts that have "gone live"
      • private/ - posts that have been "unpublished"
    • layouts/
      • default.ftl
    • static/ - used to contain theme images, css, Javascript, etc
    • uploads/ - used to contain images and downloads
  • site/ - contains the fully-rendered site

Configuring the renderer

The file .../data/config.yml contains options that controls the behavior of the renderer. The most important option is the location of the pandoc executable.

By default, the renderer will use a configuration that expects a directory structure identical to the one generated by blog --init, so you probably won't have to change many options here.

Configuring the site metadata

The file .../data/site.yml contains metadata about your website. The renderer uses this information when populating the templates found in layouts/. It should look something like this:

title: Thomas-Galvin.com
subtitle: Purveyor of File Pulp Fiction
about: The personal website of Thomas Galvin
webAddress: http://localhost

rssTitle: My Website
rssLink: http://localhost/feed/rss.xml
rssDescription: What's this all about, then?
rssCopyright: Copyright (C) 2016 All Right Reserved
rssAuthor: Author McAuthorface

You should always specify values for the above variables.

You can specify postsPerPage to control how many posts appear on each page of your history.

The index (landing) page of your website can be controlled with the landingPage variable. If landingPage is set to welcome.md, for example, the renderer will look in posts/published/ for a file called welcome.md and use that as the index page.

If no index page is specified, or if the specified file can't be found, the index page will default to a list of your most recent posts.

Finally, you can control the directory structure of your generated site with the following options:

• blogRoot - Use this to write to localhost/blog/ instead of localhost/, for example
• posts - Use this to control where posts are written. By default, posts will be written to the blog's root directory. This variable could, for example, make a post called welcome appear as http://localhost/posts/welcome instead of http://localhost/welcome.
• authors - Use this to control where an author's link page will appear. By default, it will appear in /http://localhost/authors/.
• history - Use this to change where the list of previous blog posts lives. By default, it will look like http://localhost/page/1/, http://localhost/page/2/, etc
• tags - Use this to change the directory which contains tag links. By default, it will appear in http://localhost/tags.
• feed - Use this to change the directory which contains your RSS feed By default, it will appear in http://localhost/feed.

Configuring authors

A "database" of authors can be specified in a file called src/data/authors.yml. It should look something like this:

id: thomas
displayName: Thomas
fullName: Thomas Galvin
sortByName: Galvin, Thomas
---
id: sam
displayName: Samantha
fullName: Samantha Rhodes
sortByName: Rhodes, Samantha
---
id: joe
displayName: Joe
fullName: Joe Smith
sortByName: Smith, Joe

The following options can be specified:

• id - A unique id. This will be used in post metadata, so keep it short and memorable. thomas is better than 145-098-357-232.
• displayName - The name that will show up in post bylines
• fullName - The author's full name
• sortByName - The authors name, formatted Last, First
• bio - A biography
• headshot - An image to use as a headshot in templates
• thumbnail - An image to use as a thumbnail in templates

Writing posts

The renderer will look in three different folders for your posts: .../posts/published/, .../posts/draft/, .../posts/private/. Published posts will always be rendered. Draft and private posts will only be rendered if you explicitly ask for it.

Posts can be written in either Markdown or plain HTML. The renderer will look for files that end in .md, .html, and .htm.

Post metadata

YAML-formated metadata should be included at the front of a blog post. The metadata must be fenced in with three hyphens at the front and end, like this:

---
title: Post Title
subtitle: This is a great post
author: thomas
tags:
    - Tag One
    - Tag Two
    - Tag Three
date: 2016-04-07
---
Lorem ipsum dolor sit amet, consectetur adipiscing elit, 
sed do eiusmod tempor incididunt ut labore...

The following metadata can be specified:

• title
• subtitle
• author - refers to an id in the authors.yml file
• link - e.g. hello-world. This must be unique. Generated if not specified
• date - This should be written YYYY-MM-DD
• layout - Optional, this will be "default" unless specified
• tags - a list of strings; see the example above
• pullQuote - used on link pages
• bannerImage - can be used in a custom layout to add images
• thumbnailImage - can be used in a custom layout to add images
• pullQuoteImage - can be used in a custom layout to add images

Pull quotes and pagination

By default, the entire post will appear on the landing and/or history pages. If you want to only show content "above the fold" on these pages, you can use the <!--pullquote--> markup to indicate where the front-page content ends. For example:

This content will appear on the front page.

<!--pullquote-->

And this content will only appear when the reader clicks "read more".

You can also paginate your posts, using the <!--more--> markup:

This content will appear on the front page.

<!--more-->

And this content will only appear when the reader clicks "read more".

<!--more-->

And this will only appear when the reader clicks "next page".

You can also use <!--pullquote--> and <!--more--> together:

This content will appear on the front page.

<!--pullquote-->

And this content will only appear when the reader clicks "read more".

<!--more-->

This will only appear when the reader clicks "next page".

<!--more-->

And this content will be on page 3.

Layouts

You can define arbitrary layouts in the src/layouts/ folder. We use Freemarker as our templating engine, and you can read all about how to write Freemarker templates here.

When you use blog -i, a file called src/layouts/default.ftl will be created for you, and used to generate any page that doesn't have a different layout specified. You can, however, create any kind of layout you want, just by adding a file to layouts and setting the layout property of a post.

If you have a file called src/layouts/movie-reviews.ftl, you can use it in a post by setting the layout attribute to movie-reviews.

Rendering the site

Running blog -generate or blog -g will render your blog to the .../site/ directory. The contents of .../data/static/ and .../data/uploads/ will be copied over without modification, and all posts in .../posts/published/ will be rendered to their final HTML form.

To include draft posts, run blog -g -drafts. To include private posts, run blog -g -private.

To automatically rebuild whenever a source file is changed, run blog -g -w.

To clean the site/ directory before rendering, run blog -clean -g.

Serving the site

This software includes a simple web server, so you can view your generated content without publishing it to your web host. To start the server, run blog -server or blog -s. The port can be specified with the -port option. By default, the web server will run on port 8080.

This can be included with the generate and watch commands like so: blog -gws.

When the server is running, you can visit http://localhost:8080 to see how your site will look in the wild.