Bloggo is a static site generator, in the spirit of Jekyll and Hugo. It allows an author to write articles in Markdown and provide Handlebars templates that are used to render the posts to HTML files. It also copies other static content such as images and CSS stylesheets to the destination directory, which can then be served by any web server that can serve files from the filesystem.

Usage

Most users will use the bloggo binary, rather than using the library directly.

Usage: bloggo [OPTIONS] <COMMAND>

Commands:
  clean  Clean destination directory
  build  Build static site pages
  help   Print this message or the help of the given subcommand(s)

Options:
  -s, --source <DIR>  Directory containing post and template source [default: source/]
  -o, --dest <DIR>    Directory where output will be stored [default: build/]
  -b, --base <URL>    The base URL for relative links [default: ]
  -v, --verbose       Provide verbose output
  -h, --help          Print help
  -V, --version       Print version

The layout of the source directory should appear as:

src
|-- assets
|   |-- style.css
|   |-- images
|   |   |-- example.jpg
|   |   |-- example.png
|-- templates
|   |-- index.html.hbs
|   |-- post.html.hbs
|-- posts
    |-- 2023-03-01_an_example_post.md
    |-- 2023-03-02_another_post.md

The assets directory is copied as-is to the destination directory. A file assets/style.css will copied to the build directory as style.css, and assets/images/example.jpg will be copied to images/example.jpg.

The posts directory contains the Markdown files for each post. The build phase of Bloggo will parse each post, and render an HTML file in the destination using a template. The source file is similar to other static site generators: it includes a "front matter" block, delimited to describe the format of the front matter (three hyphens for YAML), followed by the Markdown content. The front matter properties are passed into the template renderer, and some of the properties are special:

• date: If present, this is used as the date property in the Handlebars template. The expected format is the date and time format specified by ISO 8601. If not present, Bloggo will attempt to guess based on the name of the file: a file named 2023-04-05_example.md will have a date property of 2023-04-05T00:00:00Z.
• layout: The name of the template used to render this post. The name of the layout must refer to a file that appears in the templates directory with the filename extension of .html.hbs. The default value is post.
• tags: An array of strings. Bloggo generates an index and feed for each tag in the site.
• abstract: If not present, Bloggo will populate this property with the first paragraph that appears in the Markdown source.
• path: The path of the generated HTML file in the build directory. This property is generated by Bloggo.
• url: This is the URL of the post, formed by concatenating the base url with the path. This property is generated by Bloggo.

The templates directory contains the Handlebars templates used to render posts. The following two template files are required; additional template files can be used and specified by using the layout property of each post, and can also be included into other templates using the Handlebars {{> ... }} directive.

• index.html.hbs: Used to render the site and tag indexes.
• post.html.hbs: The default template for individual post pages.

The object passed into the Handlebars renderer includes the properties:

• posts: An array of Post objects to render. In the site index, this contains all of the posts in the sites. In each tag index, this contains the posts that have the tag. In individual posts, this array will contain the single post to render. Each post object contains the properties specified in the front matter.
• tags: An array of Tag objects used in the site. Each Tag object has the properties:
  • name: the name of the tag.
  • count: the number of posts with the tag.
  • index_url: The url of the index page for the tag.
• tag: The tag of the posts in the posts array, present when the tag index is being rendered.

When the bloggo build command is used with the source directory described above, the destination directory will contain

build
|-- index.html
|-- atom.xml
|-- 2023-03-01_an_example_post.html
|-- 2023-03-02_another_post.html
|-- tag-1
|   |-- index.html
|   |-- atom.xml
|-- tag-2
|   |-- index.html
|   |-- atom.xml
|-- style.css
|-- images
    |-- example.jpg
    |-- example.png

This directory can be copied to a web server that can serve static files.

Acknowledgements

Bloggo depends on a number of open source projects.

• chrono
• clap
• env_logger
• handlebars
• log
• pulldown-cmark
• serde
• serde_json
• serde_yaml
• toml

License

Bloggo is distributed under the terms of the MIT License.