blogit - mini git-based static blog generator

References

blogit - a small static blog generator

Synopsis

blogit [init|build|deploy|clean]

Description

blogit is a small static blog generator, using a markdown-like syntax and git capabilities. For example, first posted and last edited dates are extracted from git history.

Getting started

Run "blogit init" and follow the interactive configuration. This will create the basic structure and initialize a git repository.

Structure

Articles are created in the articles directory, using a markdown-like syntax (see SYNTAX). HTML templates (configurable chunks of HTML code that will be used for static page generation) are stored in the templates directory, and can be edited (see TEMPLATES). Additional data can be stored in the data directory and will be copied at the root of the website.

Workflow

The articles, templates and data can be created and edited offline. To create a local version of the blog, run "blogit build". It will be available in the blog directory, and the main page is index.html. Note that only articles known to git will be created (this is to prevent unfinished articles to be published). When its ready for publication, commit the changes to the git repository, and build the blog using "blogit build". Then run "blogit deploy" to publish the site with rsync(1) to the remote configured at the beginning.

Syntax

The first line of the article text file is its title. The next line can be blank, and will be skipped if that case. Then the remaining of the file is in a markdown format, with the following formatting options:

Sections

Sections and subsections are defined by lines starting with one or several '#', each indicating a new section level.

Paragraphs

Paragraphs are started with a blank line.

Bold, italics

Chunks enclosed in stars '*' are formatted in bold. Chunks enclosed with two stars '**' are formatted in bold.

Images

Images are inserted using the following syntax: "".

Links

Links are inserted using the following syntax: "[link text](url)".

Comments

Lines starting with a semi-colon are comments and are ignored. It can be used to store metadata. In particular, comments beginning with "tags:" indicate tags and are available in the templates in the TAGS variable.

Code blocks

Code blocks start and end with ``` (this marker must be on its own line). The content is not formatted, and will appear as writter in the source file.

Unordered lists Each item starts with "- ".

Ordered lists Each item starts with "1. ", "2. " and so on. The numbers are not checked, so any number can actually be used.

Templates

Templates are small HTML code chunks that are used to build the blog pages. Any variable reference ($VARNAME) is replaced with the corresponding environment variable value.

Index page

The index page is built using the following templates:

• header.html;
• index_header.html;
• tag_list_header.html;
• tag_entry.html, for each tag;
• tag_separator.html, between each tag;
• tag_list_footer.html;
• article_list_header.html;
• article_entry.html, for each article entry;
• article_separator.html, between each article;
• article_list_footer.html;
• index_footer.html;
• footer.html.

The TITLE variable will contain "index". In tag_entry, the following additional variables are available:

• URL, containing the (relative) URL of the tag index page;
• NAME, the tag name. In article_entry, the following additional variables are available:
• URL, containing the (relative) URL of the article;
• DATE, the first publication date;
• TITLE, the title of the article.

Article pages

Article pages are built from the following templates:

• header.html
• index_header.html
• (then the article file is formatted and inserted)
• index_footer.html
• footer.html

At all stages, the following variables are defined:

• TITLE, the title of the article;
• DATE_POSTED, the first publication date;
• DATE_EDITED, the last edit (commit) date;
• TAGS, the tags parsed from "tags:" comments.