diff options
Diffstat (limited to 'blog.1')
| -rw-r--r-- | blog.1 | 124 |
1 files changed, 124 insertions, 0 deletions
@@ -0,0 +1,124 @@ +.TH BLOG 1 blog\-1.0 +.SH NAME +blog \- a small static blog generator + +.SH SYNOPSIS +.B blog +.RB [ init | build | deploy | clean ] + +.SH DESCRIPTION +.B blog +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 "blog 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 "blog 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 "blog build". +Then run "blog 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: "". +.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. + +.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; + +- index_entry.html, for each article entry; + +- index_footer.html; + +- footer.html. + +The TITLE variable will contain "index". +In index_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. |