1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
|
.TH BLOG 1 blog\-1.0
.SH NAME
blog \- a small static blog generator
.SH SYNOPSIS
.B blog
.RB [ init | build | deploy | clean ]
.SH DESCRIPTION
.B blog
is a small static blog generator, using a markdown-like syntax and git capabilities.
For example, first posted and last edited dates are extracted from git history.
.SH GETTING STARTED
Run "blog init" and follow the interactive configuration.
This will create the basic structure and initialize a git repository.
.SH STRUCTURE
Articles are created in the
.B articles
directory, using a markdown-like syntax (see
.BR SYNTAX ).
HTML templates (configurable chunks of HTML code that will be used for static page generation) are stored in the
.B templates
directory, and can be edited (see
.BR TEMPLATES ).
Additional data can be stored in the
.B data
directory and will be copied at the root of the website.
.SH WORKFLOW
The articles, templates and data can be created and edited offline.
To create a local version of the blog, run "blog build".
It will be available in the
.B blog
directory, and the main page is index.html.
Note that only articles known to git will be created (this is to prevent unfinished articles to be published).
When its ready for publication, commit the changes to the git repository, and build the blog using "blog build".
Then run "blog deploy" to publish the site with
.BR rsync (1)
to the remote configured at the beginning.
.SH SYNTAX
The first line of the article text file is its title.
The next line can be blank, and will be skipped if that case.
Then the remaining of the file is in a markdown format, with the following formatting options:
.TP
.B Sections
Sections and subsections are defined by lines starting with one or several
.RB ' # ',
each indicating a new section level.
.TP
.B Paragraphs
Paragraphs are started with a blank line.
.TP
.B Bold, italics
Chunks enclosed in stars
.RB ' * '
are formatted in bold.
Chunks enclosed with two stars
.RB ' ** '
are formatted in bold.
.TP
.B Images
Images are inserted using the following syntax: "".
.TP
.B Links
Links are inserted using the following syntax: "[link text](url)".
.TP
.B Comments
Lines starting with a semi-colon are comments and are ignored.
It can be used to store metadata.
In particular, comments beginning with "tags:" indicate tags and are available in the templates in the TAGS variable.
.SH TEMPLATES
Templates are small HTML code chunks that are used to build the blog pages.
Any variable reference
.RB ( $VARNAME )
is replaced with the corresponding environment variable value.
.SS Index page
The index page is built using the following templates:
- header.html;
- index_header.html;
- index_entry.html, for each article entry;
- index_footer.html;
- footer.html.
The TITLE variable will contain "index".
In index_entry, the following additional variables are available:
- URL, containing the (relative) URL of the article;
- DATE, the first publication date;
- TITLE, the title of the article.
.SS Article pages
Article pages are built from the following templates:
- header.html
- index_header.html
- (then the article file is formatted and inserted)
- index_footer.html
- footer.html
At all stages, the following variables are defined:
- TITLE, the title of the article;
- DATE_POSTED, the first publication date;
- DATE_EDITED, the last edit (commit) date;
- TAGS, the tags parsed from "tags:" comments.
|
