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