diff options
Diffstat (limited to 'blogit.1')
| -rw-r--r-- | blogit.1 | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/blogit.1 b/blogit.1 new file mode 100644 index 0000000..ebdaaa4 --- /dev/null +++ b/blogit.1 @@ -0,0 +1,157 @@ +.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: "". +.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. |