.TH BLOG 1 blogit\-1.0
.SH NAME
blogit \- a small static blog generator

.SH SYNOPSIS
.B blogit
.RB [ init | build | deploy | clean ]

.SH DESCRIPTION
.B 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.

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

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

.SH 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
.B 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
.BR rsync (1)
to the remote configured at the beginning.

.SH 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:
.TP
.B Sections
Sections and subsections are defined by lines starting with one or several 
.RB ' # ',
each indicating a new section level.
.TP
.B Paragraphs
Paragraphs are started with a blank line.
.TP
.B Bold, italics
Chunks enclosed in stars
.RB ' * '
are formatted in bold.
Chunks enclosed with two stars
.RB ' ** '
are formatted in bold.
.TP
.B Images
Images are inserted using the following syntax: "![alternate text](url)".
.TP
.B Links
Links are inserted using the following syntax: "[link text](url)".
.TP
.B 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.
.TP
.B 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.
.TP
.B
Unordered lists
Each item starts with "- ".
.TP
.B
Ordered lists
Each item starts with "1. ", "2. " and so on.
The numbers are not checked, so any number can actually be used.

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

.SS 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.

.SS 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.