Happy new year 2022!
[web-old.git] / 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.