aboutsummaryrefslogtreecommitdiffstats
path: root/man/blogc-source.7.ronn
blob: 2b2b11efddba930f604ce5554860a3d4a5dfb94b (plain)
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
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
blogc-source(7) -- blogc's source file format
=============================================

## DESCRIPTION

Source files are used as input data to the blogc(1) compiler. They provide
variables and content, that are used by the compiler to fill the gaps available
in the templates (see blogc-template(7)).

The syntax of the source files is designed to be as simple as possible. The
variables are defined in the top of the file as key-value lines, and the
content is defined right after the variables.

Content is written in a markup language that is similar to John Gruber's
Markdown, but that is NOT Markdown. This language is very simple, while
powerful enough to write big posts.

## SOURCE VARIABLES

Variables are key-value lines. The variable name must be upper-case, starting
with a letter and following with one or more letters and/or underscores. The
value is separated from the variable name with a ':' and finishes in the end
of the line. Multi-line values are not supported.

    VARIABLE1: Value of variable one
    VARIABLE2: Value of variable two
    --------------------------------

All the variables defined in the source files are local and will override
global variables provided to blogc(1) in the command-line, but just inside
blocks that handle local variables. See blogc-template(7) for details.

The ``DATE`` variable is special, and represents the publishing date of the
post. It may be formatted with the ``DATE_FORMAT`` variable, if provided,
otherwise will be kept as is. See blogc(1).

## SOURCE CONTENT - BLOCK ELEMENTS

### Paragraphs

Paragraphs are simple blocks of text.

    This is a paragraph.

    This is another paragraph.

### Headers

Headers are defined starting with '#' characters, then number of characters is
the level of the header.

    # H1

    ## H2

    ### H3

    #### H4

### Blockquotes

Blockquotes are defined with lines starting with '>' characters. Content defined
inside a blockquote is parsed again, so all the block elements are allowed inside
blockquotes. The indentation after the '>' character must be preserved in the
begin of each blockquote line.

    > Hello,
    > 
    > This is the blockquote example!

### Unordered Lists

Unordered lists are defined with lines starting with '*', '+' or '-'. The same
starting character must be used for all the list items, and the indentation after
the starting character must be preserved in the begin of each line.

    * First item
    * Second item
    * Third item

Multi-line items are supported. Content must be aligned properly:

    * First item
      Continuation of first item
    * Second item
    * Third item

### Ordered Lists

Ordered lists are defined with lines starting with a number and a '.' character.
The indentation after the starting character must be preserved in the begin of
each line, meaning that the content of the items must be aligned. The order and
value of the numbers is ignored.

    1.  First item
    2.  Second item
    10. Tenth item

Multi-line items are supported. Content must be aligned properly:

    1.  First item
        Continuation of first item
    2.  Second item
    10. Tenth item

To use numbers with '.' character in a non-list string, you must escape the '.'.

    1234\. This is not a list

### Code Blocks

Code blocs are defined by indenting the lines with one or more whitespace characters.

    This is a paragraph.

        This is a code block.
        Some more code.

    This is another paragraph.

### Horizontal Rules

Horizontal rules are defined as a paragraph with a sequence of 2 or more '*', '+'
or '-' characters.

    This is a paragraph before horizontal rule

    ***

    This is a paragraph after horizontal rule

The horizontal rule must not be on its own paragraph, otherwise it will be parsed
as a continuation of the previous paragraph.

### HTML Blocks

HTML blocks are paragraphs started with '<' character. Everything is kept untouched
in HTML blocks, until the next paragraph.

    <p>This is raw HTML</p>

    This is an usual paragraph

    <p>This is more raw HTML</p>

### Excerpt Separator

The excerpt is separated from the full content of a page/post using a paragraph with
a sequence of 2 or more '.' characters.

After parsing, the excerpt will be part of the full content as well.

## SOURCE CONTENT - INLINE ELEMENTS

### Bold

Bold text is defined with 2 '*' or '_' before and after the text.

    Bold text: **text**
    Bold text: __text__

### Italic

Italic text is defined with 1 '*' or '_' before and after the text.

    Italic text: *text*
    Italic text: _text_

### Bold and Italic

Bold and italic text is defined mixing markers, like:

    Italic and bold text: _**text**_
    Italic and bold text: *__text__*
    Italic and bold text: __*text*__
    Italic and bold text: **_text_**

### Code

Code is defined with 1 or 2 '`' before and after the text.

    This is inline code: `code`
    This is inline code: ``code``

### Images

Images are defined using the following syntax:

    This is an image: ![This is the image alt text](picture.jpg)

### Links

Links are defined using the following syntax:

    To learn more about blogc, [click here](http://blogc.org).

### Image Links

Links can be combined with images:

    [![This is the image alt text](picture.jpg)](http://blogc.org)

### Automatic Links

Automatic link is defined with 2 '[' before and 2 ']' after the URL.

    To learn more about blogc, visit [[http://blogc.org]].

### Line break

Line breaks can be added after a paragraph line adding 2 or more white spaces
to the end of the line.


## BUGS

The source 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>

At least one bug is known at this point: ``\r\n`` character sequences are
handled like 2 line breaks. The parsers won't work properly with files edited
on Windows editors like Notepad.

## AUTHOR

Rafael G. Martins &lt;<rafael@rafaelmartins.eng.br>&gt;

## SEE ALSO

blogc(1), blogc-template(7), strptime(3)