blogcfile - Man Page
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.
- atom_template (default: internal template) The template file that should be used when building Atom feeds. This file is relative to template_dir. If not provided, an internal default template will be used instead. The internal template can be dumped using the atom_dump blogc-make(1) rule.
- blog_prefix (default: unset): If set, the value is added as a prefix to index, posts, tags, pagination, atom feeds and any other resources related to blog posts. This setting is useful to deploy the whole blog section of a website into a sub URL like "blog".
- 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.
- listing_entry (default: unset): The page that will be included in the listing pages of the website, without the page prefix and without the extension, only the "slug" should be used. See blogc(1) and the description of listing_entry block in blogc-template(7) for details.
- 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.
- posts_sort (default: false): If true, blogc(1) will sort the posts by date, despite the order of the posts in the [posts] section, in descending order. This setting is compatible with html_order and atom_order settings, to control the order of the posts.
- run_from_make (default: false): If true, enforces blogc-make(1) to check if it is running as a make(1) subprocess, and exit with an error otherwise. This is useful when blogc-make(1) is called by make(1) as part of a larger build infrastructure, and calling blogc-make(1) directly could cause errors due to some generated dependencies missing.
- 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 <rafael@rafaelmartins.eng.br>
See Also
blogc(1), blogc-make(1), make(1), blogc-template(7), strftime(3)
Referenced By
blogc-git-receiver(1), blogc-make(1).