tribo

Tribo - A static blog generator

Named after the Triboelectric effect which is a cause of static electricity.

I created this for my own personal use but feel free to use it if you want.

Quick Start

First you need to install the Tribo executable:

go get github.com/cswilson90/tribo/cmd/tribo

This will install the tribo executable in $GOPATH. It's recommended you add the location of $GOPATH to $PATH so the program can be executed anywhere.

To quickly get the example blog running run the following commands:

$ git clone https://github.com/cswilson90/tribo.git
$ cd tribo/example
$ tribo

This will build the example blog and install it in /srv/blog.

If you have your own blog directory already set up you should run the tribo command from that directory.

To view the blog you will then need to install and run a webserver. Below is an example nginx config to serve the site.

server {
    listen 80 default_server;
    listen [::]:80 default_server;

    root /srv/blog;

    index index.html;

    server_name _;

    location / {
        try_files $uri $uri/ =404;
    }
}

You can use any webserver. You just need to configure it to serve static files out of /srv/blog. You will also need to make sure it is setup to use index.html as an index page.

You can then view the example blog by visiting http://127.0.0.1/ in a browser on the machine running the webserver.

Program Output

Blog post listing

The program generates a listing of all blog posts available on the blog. This is stored in index.html in the root directory of the blog so is the default page seen when visting http://127.0.0.1/.

Blog posts

Each blog post is stored in it's own directory. The directory the post will be stored in is formed from the publish date and title of the post. If a post has the title "Test Post" and a publish date of "1st April 2021" it will be stored in 2021/04/test-post/ and will be available at the URL http://127.0.0.1/2021/04/test-post/.

RSS feed

By default the program will generate an RSS feed for the blog and save it as rss.xml in the root output directory. This will be available on the webserver at http://127.0.0.1/rss.xml.

You can disabled generation of the RSS feed using the noRss configuration option.

Blog Directory Layout

The example directory gives an example layout of a blog. This uses the default name for each directory but you can change the directory names as described in the program configuration section below.

example/
+--posts/
|  +--2021/
|     +--01/
|     |  +--content.md
|     |  +--metadata.yaml
|     +--03/
|        +--image-post/
|        |  +--resources/
|        |  |  +--cat.jpg
|        |  +--content.md
|        |  +--metadata.yaml
|        +--post-2
|           +--content.md
|           +--metadata.yaml
|
+--static/
|  +--blog.css
|  +--blog.js
|
+--templates/
|  +--includes/
|  |  +--header.html.tmpl
|  |  +--footer.html.tmpl
|  +--post.html.tmpl
|  +--post_list.html.tmpl
|
+--.tribo.yaml

Post Files

posts/ is where you should but all the content and config for your individual blog posts.

Tribo will recursively walk the posts/ directory looking for posts. A post is any directory that contains both a content.md and metadata.yaml file. If a directory contains both files the program will look no further down the directory tree so post directories can't themselves contain sub-directories which are posts.

The example orders the posts by year and month but you can order the directories in whatever way you want. However, no matter how you order the input directories the output will be grouped by into directories by year and month of publication.

As well as year and month directories each post is also given it's own directory based on it's title. In the example the post at posts/2021/01/ is available at http://127.0.0.1/2021/01/my-first-post/.

A post directory can contain the following:

• content.md (required) - a markdown file containing the content of the blog post. The first thing in the content file should be a heading with the title of the post. The content of the heading is extracted and used as the title. The first paragraph of the content is extracted and used as a preview on the posts list page.
• metadata.[yaml|json] (required) - a YAML or JSON file containing metadata for the the blog post, see the post metadata section for information on the data that can be provided.
• resources/ (optional) - a directory containing static resources used in the post e.g. images. These will be copied to the root of the output blog post directory e.g. in the example image-post uses an image at http://127.0.0.1/2021/03/a-post-with-an-image/cat.jpg. This is linked to in content.md using a relative link e.g. ![Cat Image](cat.jpg)

Static Files

static/ is where you should put any static resources that will be used throughout the site such as javascript, CSS and images.

The resources will be copied to the root directory of the output so will be available at e.g. http://127.0.0.1/blog.js for blog.js in the example

Template Files

templates/ is where you should put templates for generating the static pages. See the writing your own templates section for more information about customising the templates.

Config File

This is a YAML config file that can be used to set Tribo run time options. See the program configuration section for information on what can be configured in the file. By default running tribo in the directory with no arguments will load config from this file.

The YAML should be a single hash where each key is a config option e.g.

---
outputDir: /srv/blog
blogName:  "My Blog"

Post Metadata

The metadata for a post should be given in a file called metadata.yaml or metadata.json in the post's directory.

The following options can be given:

An example of the contents of a metadata YAML file:

---
publishdate: "2021-03-10"
tags:
  - fun
  - aboutme

Program Configuration

Tribo has several configuration options that can be set either with a command line argument or in a YAML config file.

By default the program will try to read config from a file called .tribo.yaml in the working directory (generally the directory the program is executed in). You can specify a different config file by supplying the -configFile argument when running the tribo executable. If you don't specify a config file when executing the program and no .tribo.yaml file exists the default value will be used for all options.

The following can be configured:

Writing Your Own Templates

Templates use golang's html/template package.

There are two main template files in the templates directory:

• post.html.tmpl - used to generate the page for a single post
• post_list.html.tmpl - used to generate the list of posts that is used as the main page of the blog

The template folder also contains a includes/ directory in which you can put templates which are included in the two main files. In the example this is just the header and footer but more can be added if required.

A postPageData object is passed in as the input to post.html.tmpl and a postListPageData object is passed to post_list.html.tmpl. The structure of the objects is as follows:

postPageData {
    Common: commonData, // Data common to all pages
    Post:   postData,   // Data for the post to be displayed on the page
}

postListPageData {
    Common:  commonData,   // Data common to all pages
    Posts:   [ postData ], // A list of data for each post in the list (sorted by publish date)
    AllTags: [ string ],   // A list of all tags from all posts (ordered alphabetically)
}

commonData {
    BaseURLPath:    string, // The base path of the blog on the server
    BlogName:       string, // The global name of the blog
    BlogDescription string, // The global description of the blog
    PageTitle:      string, // A title for the page to be used as the HTML title
    CurrentYear:    string, // The current year as a string (for use in copyright notice)
}

postData {
    Title:       string,        // The title of the blog post
    Content:     template.HTML, // The HTML content of the post (in a format compatible with the `html/template` package)
    Preview:     template.HTML, // The HTML content of the preview of the post
    PublishDate: string         // The publish date of the blog post in "01 Jan 2000" format
    Url:         string         // The direct URL link for the post
    Tags:        [ string ]     // A list of tags attached to the post
}

References

The example given makes use of list.js.