DeckPC - Day one
[web-old.git] / blogit.1
CommitLineData
0324a0cf
JM
1.TH BLOG 1 blogit\-1.0
2.SH NAME
3blogit \- 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
11is a small static blog generator, using a markdown-like syntax and git capabilities.
12For example, first posted and last edited dates are extracted from git history.
13
14.SH GETTING STARTED
15Run "blogit init" and follow the interactive configuration.
16This will create the basic structure and initialize a git repository.
17
18.SH STRUCTURE
19Articles are created in the
20.B articles
21directory, using a markdown-like syntax (see
22.BR SYNTAX ).
23HTML templates (configurable chunks of HTML code that will be used for static page generation) are stored in the
24.B templates
25directory, and can be edited (see
26.BR TEMPLATES ).
27Additional data can be stored in the
28.B data
29directory and will be copied at the root of the website.
30
31.SH WORKFLOW
32The articles, templates and data can be created and edited offline.
33To create a local version of the blog, run "blogit build".
34It will be available in the
35.B blog
36directory, and the main page is index.html.
37Note that only articles known to git will be created (this is to prevent unfinished articles to be published).
38When its ready for publication, commit the changes to the git repository, and build the blog using "blogit build".
39Then run "blogit deploy" to publish the site with
40.BR rsync (1)
41to the remote configured at the beginning.
42
43.SH SYNTAX
44The first line of the article text file is its title.
45The next line can be blank, and will be skipped if that case.
46Then the remaining of the file is in a markdown format, with the following formatting options:
47.TP
48.B Sections
49Sections and subsections are defined by lines starting with one or several
50.RB ' # ',
51each indicating a new section level.
52.TP
53.B Paragraphs
54Paragraphs are started with a blank line.
55.TP
56.B Bold, italics
57Chunks enclosed in stars
58.RB ' * '
59are formatted in bold.
60Chunks enclosed with two stars
61.RB ' ** '
62are formatted in bold.
63.TP
64.B Images
65Images are inserted using the following syntax: "![alternate text](url)".
66.TP
67.B Links
68Links are inserted using the following syntax: "[link text](url)".
69.TP
70.B Comments
71Lines starting with a semi-colon are comments and are ignored.
72It can be used to store metadata.
73In particular, comments beginning with "tags:" indicate tags and are available in the templates in the TAGS variable.
74.TP
75.B Code blocks
76Code blocks start and end with ``` (this marker must be on its own line).
77The content is not formatted, and will appear as writter in the source file.
78.TP
79.B
80Unordered lists
81Each item starts with "- ".
82.TP
83.B
84Ordered lists
85Each item starts with "1. ", "2. " and so on.
86The numbers are not checked, so any number can actually be used.
87
88.SH TEMPLATES
89Templates are small HTML code chunks that are used to build the blog pages.
90Any variable reference
91.RB ( $VARNAME )
92is replaced with the corresponding environment variable value.
93
94.SS Index page
95The 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
121The TITLE variable will contain "index".
122In 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
128In 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
137Article 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
149At 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.