blogit.1

   1 .TH BLOG 1 blogit\-1.0
   2 .SH NAME
   3 blogit \- a small static blog generator
   4
   5 .SH SYNOPSIS
   6 .B blogit
   7 .RB [ init | build | deploy | clean ]
   8
   9 .SH DESCRIPTION
  10 .B blogit
  11 is a small static blog generator, using a markdown-like syntax and git capabilities.
  12 For example, first posted and last edited dates are extracted from git history.
  13
  14 .SH GETTING STARTED
  15 Run "blogit init" and follow the interactive configuration.
  16 This will create the basic structure and initialize a git repository.
  17
  18 .SH STRUCTURE
  19 Articles are created in the
  20 .B articles
  21 directory, using a markdown-like syntax (see
  22 .BR SYNTAX ).
  23 HTML templates (configurable chunks of HTML code that will be used for static page generation) are stored in the
  24 .B templates
  25 directory, and can be edited (see
  26 .BR TEMPLATES ).
  27 Additional data can be stored in the
  28 .B data
  29 directory and will be copied at the root of the website.
  30
  31 .SH WORKFLOW
  32 The articles, templates and data can be created and edited offline.
  33 To create a local version of the blog, run "blogit build".
  34 It will be available in the
  35 .B blog
  36 directory, and the main page is index.html.
  37 Note that only articles known to git will be created (this is to prevent unfinished articles to be published).
  38 When its ready for publication, commit the changes to the git repository, and build the blog using "blogit build".
  39 Then run "blogit deploy" to publish the site with
  40 .BR rsync (1)
  41 to the remote configured at the beginning.
  42
  43 .SH SYNTAX
  44 The first line of the article text file is its title.
  45 The next line can be blank, and will be skipped if that case.
  46 Then the remaining of the file is in a markdown format, with the following formatting options:
  47 .TP
  48 .B Sections
  49 Sections and subsections are defined by lines starting with one or several
  50 .RB ' # ',
  51 each indicating a new section level.
  52 .TP
  53 .B Paragraphs
  54 Paragraphs are started with a blank line.
  55 .TP
  56 .B Bold, italics
  57 Chunks enclosed in stars
  58 .RB ' * '
  59 are formatted in bold.
  60 Chunks enclosed with two stars
  61 .RB ' ** '
  62 are formatted in bold.
  63 .TP
  64 .B Images
  65 Images are inserted using the following syntax: "![alternate text](url)".
  66 .TP
  67 .B Links
  68 Links are inserted using the following syntax: "[link text](url)".
  69 .TP
  70 .B Comments
  71 Lines starting with a semi-colon are comments and are ignored.
  72 It can be used to store metadata.
  73 In particular, comments beginning with "tags:" indicate tags and are available in the templates in the TAGS variable.
  74 .TP
  75 .B Code blocks
  76 Code blocks start and end with ``` (this marker must be on its own line).
  77 The content is not formatted, and will appear as writter in the source file.
  78 .TP
  79 .B
  80 Unordered lists
  81 Each item starts with "- ".
  82 .TP
  83 .B
  84 Ordered lists
  85 Each item starts with "1. ", "2. " and so on.
  86 The numbers are not checked, so any number can actually be used.
  87
  88 .SH TEMPLATES
  89 Templates are small HTML code chunks that are used to build the blog pages.
  90 Any variable reference
  91 .RB ( $VARNAME )
  92 is replaced with the corresponding environment variable value.
  93
  94 .SS Index page
  95 The index page is built using the following templates:
  96
  97 - header.html;
  98
  99 - index_header.html;
 100
 101 - tag_list_header.html;
 102
 103 - tag_entry.html, for each tag;
 104
 105 - tag_separator.html, between each tag;
 106
 107 - tag_list_footer.html;
 108
 109 - article_list_header.html;
 110
 111 - article_entry.html, for each article entry;
 112
 113 - article_separator.html, between each article;
 114
 115 - article_list_footer.html;
 116
 117 - index_footer.html;
 118
 119 - footer.html.
 120
 121 The TITLE variable will contain "index".
 122 In tag_entry, the following additional variables are available:
 123
 124 - URL, containing the (relative) URL of the tag index page;
 125
 126 - NAME, the tag name.
 127
 128 In article_entry, the following additional variables are available:
 129
 130 - URL, containing the (relative) URL of the article;
 131
 132 - DATE, the first publication date;
 133
 134 - TITLE, the title of the article.
 135
 136 .SS Article pages
 137 Article pages are built from the following templates:
 138
 139 - header.html
 140
 141 - index_header.html
 142
 143 - (then the article file is formatted and inserted)
 144
 145 - index_footer.html
 146
 147 - footer.html
 148
 149 At all stages, the following variables are defined:
 150
 151 - TITLE, the title of the article;
 152
 153 - DATE_POSTED, the first publication date;
 154
 155 - DATE_EDITED, the last edit (commit) date;
 156
 157 - TAGS, the tags parsed from "tags:" comments.