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
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
blogc-template(7) -- blogc's template format
============================================
## DESCRIPTION
Template files are used as base to build output files by blogc(1). These files
can include variables, blocks and conditionals, that will directly affect the
output files.
The syntax of the template files is defined to be simple, without affecting the
content output. The syntax is somewhat inspired by Jinja2 syntax.
This manual describes the basic syntax and functionalities of template files.
## TEMPLATE BLOCKS
Template blocks are used to delimit content. The content inside a block will
be included in the output file (or not) if the parameters passed to blogc(1)
matches the requirements of the given block.
Blocks can be defined more than once, but can't be nested.
The available blocks are: `entry`, `listing` and `listing_once`.
### entry block
The content of an `entry` block is included in the output file when blogc(1)
is called without `-l` option, and with only one source file. It is used to
render a single entry of your blog/website. All the variables defined in the
source file are available inside this block (see blogc-source(7)), and will
override global variables (see blogc(1)).
This is how an `entry` block is defined:
{% block entry %}
This content will only be included when rendering a single entry.
{% endblock %}
### listing block
The content of a `listing` block is included in the output file when blogc(1)
is called with `-l` option, and with zero or more source files. It is used
to create a listing of entries, and its content will be included once for
each given source file (in the order that the source files were provided to
blogc(1)). All the variables defined in the source files are available
inside this block (see blogc-source(7)), and will override global variables
(see blogc(1)). The variables will be provided by each file, when blogc(1)
iterates over them.
This is how a `listing` block is defined:
{% block listing %}
This content will be only included when rendering an entry listing, and
will be included once for each entry.
{% endblock %}
### listing_once block
The content of a `listing_once` block is included in the output file when
blogc(1) is called with `-l` option, and with zero or more source files. It is
like a `listing` block, but is only called once, and does not have access
to the local variables defined in the source files. It is useful to add
something before an entry listing.
The content of a `listing_once` block is included even if no source file is
provided.
This is how a `listing_once` block is defined:
{% block listing_once %}
This content will be only included when rendering an entry listing, but
will be included only once.
{% endblock %}
This is a 'real life' usage example of a `listing_once` block, supposing
that each source file defines a `TITLE` variable:
{% block listing_once %}
<ul>
{% endblock %}
{% block listing %}
<li>{{ TITLE }}</li>
{% endblock %}
{% block listing_once %}
</ul>
{% endblock %}
## TEMPLATE VARIABLES
Template variables are used to provide content to templates from blogc(1)
command-line and from source files.
This is how a variable is defined in a template:
{{ VARIABLE_NAME }}
The value of a variable will depends of its scope. Global variables provided
to blogc(1) are available everywhere in the templates. Local variables
provided in the source files are available only inside `entry` and `listing`
blocks, and will override global variables.
If a variable is not defined, it will be replaced by an empty string. blogc(1)
won't raise any error in this case.
Variables are always strings, even if the value of the variable is a number,
it is handled as a string by blogc(1).
## TEMPLATE CONDITIONALS
Template conditionals are used to include content to the output, or not,
based on the value and existence of variables in the current scope.
The implementation of conditionals is simple, and each will just evaluate the
value of a single variable.
The available conditionals are: `ifdef`, `ifndef` and `if`.
### ifdef conditional
The content of an `ifdef` conditional is included in the output file when
the given variable is defined in the current scope.
This is how an `ifdef` conditional is defined in a template:
{% ifdef TITLE %}
This is title: {{ TITLE }}
{% endif %}
In this case, if the `TITLE` variable is defined, the content is included.
### ifndef conditional
The content of an `ifndef` conditional is included in the output file when
the given variable is not defined in the current scope.
This is how an `ifndef` conditional is defined in a template:
{% ifndef TITLE %}
Untitled entry
{% endif %}
In this case, if the `TITLE` variable is not defined, the content is included.
### if conditional
The content of an `if` conditional is included in the output file when
the comparision between the given variable and the given static string or
variable evaluates to true in the current scope.
The available operators are: `==`, `!=`, `<`, `>`, `<=` and `>=`. The
comparisions are strcmp(3)-like.
This is how an `if` conditional is defined in a template:
{% if TITLE == "My Title" %}
Title is "My Title"
{% endif %}
Or:
{% if TITLE == DEFAULT_TITLE %}
Title is the default title
{% endif %}
## BUGS
The template content is handled by handwritten parsers, that even being well
tested, may be subject of parsing bugs. Please report any issues to:
<https://github.com/blogc/blogc>
## AUTHOR
Rafael G. Martins <<rafael@rafaelmartins.eng.br>>
## SEE ALSO
blogc(1), blogc-source(7), strcmp(3)
|
