aboutsummaryrefslogtreecommitdiffstats
path: root/man/blogcfile.5.ronn
blob: 61812a413ee0cb3803e44475339759ea862a6faf (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
blogcfile(5) -- blogc-make's configuration file
===============================================

## DESCRIPTION

**blogcfile** is the configuration file for blogc-make(1), that is a simple
build tool for blogc(1). It is an INI-style file, with some predefined
sections, that will provide the data required by blogc-make(1) rules to
build websites.

**blogcfile** must be valid UTF-8.

## OPTIONS

### Global variables

The `[global]` section contains all the blogc(1) variables that should be
passed to all blogc(1) calls.

The following variables are required and should be always provided:

  * `AUTHOR_NAME`:
    The name of the website main author.

  * `AUTHOR_EMAIL`:
    The email of the website main author.

  * `BASE_DOMAIN`:
    The base domain of the website.

  * `SITE_TITLE`:
    The website title.

  * `SITE_TAGLINE`:
    The website tagline.

### Settings

blogc-make(1) relies on a predefined set of rules to build the websites,
however these rules can be customized with the following settings, from the
`[settings]` section:

  * `atom_ext` (default: `.xml`):
    The extension of the generated Atom feeds.

  * `atom_order` (default: `DESC`):
    The ordering (`ASC` or `DESC`) of the Atom feeds. Please note that the files
    are not sorted by date, they are sorted by their order in the `[posts]`
    section.

  * `atom_posts_per_page` (default: `10`):
    Number of posts per page in the Atom feeds. If negative, all the posts are
    included. If `0`, no Atom feeds are generated.

  * `atom_prefix` (default: `atom`):
    The prefix of the generated Atom feeds. It is relative to the output
    directory. With the default values of the settings, the main Atom feed will
    be `atom.xml`, the Atom feed for the `foo` tag will be `atom/foo.xml` and so
    on.

  * `content_dir` (default: `content`):
    The directory that stores the source files. This directory is relative
    to `blogcfile`.

  * `date_format` (default: `%b %d, %Y, %I:%M %p GMT`):
    The strftime(3) format that should be used when formating dates. Please note
    that the times are always handled as UTC/GMT.

  * `html_ext` (default: `/index.html`):
    The extension of the generated HTML files. The default value will result on
    friendly URL, by creating directories with `index.html` files inside, instead
    of creating the HTML file directly. The `index` page is a special case:
    instead of generating something like `/index/index.html`, it will generate
    `/index.html`, because this is behavior that most users would expect.

  * `html_order` (default: `DESC`):
    The ordering (`ASC` or `DESC`) of the posts in the listing indexes.
    Please note that the files are not sorted by date, they are sorted by
    their order in the `[posts]` section.

  * `index_prefix` (default: unset):
    The prefix of the index HTML page, that is the listing of blog posts. This
    option is useful if the user wants to host a page in the root of the website,
    and move the posts listing index to a subdirectory.

  * `locale` (default: unset):
    The locale to be used when calling blogc(1). E.g. `en_US.UTF-8`.

  * `main_template` (default: `main.tmpl`):
    The template file that should be used when building HTML files. This file
    is relative to `template_dir`.

  * `pagination_prefix` (default: `page`):
    The prefix of the generated pagination pages. It is relative to the
    output directory.

  * `post_prefix` (default: `post`):
    The prefix of the posts file names. It is used for both content and output
    directories, and is relative to `content_dir` and the output directory.

  * `posts_per_page` (default: `10`):
    Number of posts per page in the pagination pages. If negative, all the posts
    are included. If `0`, no post listing pages are generated. Also, if negative or
    `0`, the `pagination` build rule is disabled.

  * `source_ext` (default: `.txt`):
    The extension of the source files.

  * `tag_prefix` (default: `tag`):
    The prefix of the generated tag listing index pages. It is relative to the
    output directory.

  * `template_dir` (default: `templates`):
    The directory that stores the template files. This directory is relative
    to `blogcfile`.

### Posts listing

The `[posts]` section is a listing of the posts that will be included in the
website. They should be listed without the post prefix and without the extension,
only the "slugs" should be used. For example, with default settings, if the source
of the post is `content/post/foo.txt`, the line added to the `[posts]` section
is `foo`.

All the posts are relative to the `post_prefix` in the root of the website.

### Pages listing

The `[pages]` section is a listing of the pages that will be included in the
website. They should be listed without the page prefix and without the extension,
only the "slugs" should be used. For example, with default settings, if the source
of the page is `content/foo.txt`, the line added to the `[pages]` section is `foo`.

All the pages are relative to the root of the website.

### Tags listing

The `[tags]` section is a listing of the tags that should be listed in the
website. blogc-make(1) will generate post listing indexes and Atom feeds for
each tag listed in the section.

The tags will be also provided to blogc as a `MAKE_TAGS` variable, that is a
space-separated list of the tags, useful to generate tag clouds using the
`foreach` template iterator. See blogc-template(7).

### Copy listing

The `[copy]` section is a listing of the files that should be copied to the
output directory.

All the files are relative to the `blogcfile`, and their directory structure
will be built inside the output directory.

## EXAMPLE

    [global]
    AUTHOR_NAME = Author
    AUTHOR_EMAIL = author@example.org
    SITE_TITLE = Site Title
    SITE_TAGLINE = Site Tagline
    BASE_DOMAIN = http://example.org

    [settings]
    locale = en_US.utf8

    [posts]
    post1
    post2

    [pages]
    about

    [tags]
    tag1
    tag2

    [copy]
    assets/custom.css

## BUGS

Please report any issues to: <https://github.com/blogc/blogc>

## AUTHOR

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

## SEE ALSO

blogc(1), blogc-make(1), blogc-template(7) strftime(3)