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: "![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. |