projects / web-old.git / blame
| Commit | Line | Data |
|---|---|---|
| 0324a0cf JM |
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: "". | |
| 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. |