BLOGCFILE(5)

📦
version 0.20.1^20240602.b1ae9c9 · 3 versions
, in fedora 43

💖 BLOGCFILE(5) 💖

okay bestie, welcome to the blogc manual, page five, section five, and honestly? this one's a whole vibe. it's giving "configuration file that runs the whole website" energy. let's go 🎀

✨ NAME ✨

blogcfile — the configuration file for blogc-make(1). that's it, that's the girl. 💅

🌸 DESCRIPTION 🌸

so blogcfile is the config file for blogc-make(1), which is a simple build tool for blogc(1). it's an INI-style file, lowkey, with some predefined sections, and it hands over all the data that blogc-make(1) rules need to build websites. no cap, that's the entire job. 🫶

🚨 important bestie: blogcfile must be valid UTF-8. no weird encodings in the group chat, please.

👑 OPTIONS 👑

🌈 Global variables

the [global] section holds all the blogc(1) variables that should be passed to all blogc(1) calls. every single one of them. periodt.

the following variables are required and should always be provided (yes, always, i'm not playing):

  • AUTHOR_NAME — the name of the website main author. who's the main character? it's them. ⭐
  • AUTHOR_EMAIL — the email of the website main author. so people can reach the icon.
  • 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, but bestie, those rules are customizable. here's everything you can tweak, all 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. > ⚠️ heads up: the files are not sorted by date, they're sorted by their order in the [posts] section. read that twice, bestie.
  • 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 at all. 💀
  • atom_prefix (default: atom) — the prefix of the generated Atom feeds. it's 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. cute, right?
  • atom_template (default: internal template) — the template file that should be used when building Atom feeds. this file is relative to template_dir. if you don't provide it, an internal default template gets used instead. you can dump that internal template with 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. super useful if you wanna 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. relative to blogcfile.
  • date_format (default: %b %d, %Y, %I:%M %p GMT) — the strftime(3) format used when formating dates. > ⚠️ note: the times are always handled as UTC/GMT. no local timezone shenanigans.
  • html_ext (default: /index.html) — the extension of the generated HTML files. the default value gives you friendly URLs 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 generates /index.html, because that's the behavior most users would expect. slay, honestly.
  • html_order (default: DESC) — the ordering (ASC or DESC) of the posts in the listing indexes. > ⚠️ same deal: files are not sorted by date, they're sorted by their order in the [posts] section.
  • index_prefix (default: unset) — the prefix of the index HTML page, aka the listing of blog posts. useful if you wanna 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 the 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 used when building HTML files. relative to template_dir.
  • pagination_prefix (default: page) — the prefix of the generated pagination pages. relative to the output directory.
  • post_prefix (default: post) — the prefix of the posts file names. used for both content and output directories, and 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. compatible with the 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's running as a make(1) subprocess, and exit with an error otherwise. 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. bestie, protect yourself. 🛡️
  • source_ext (default: .txt) — the extension of the source files.
  • tag_prefix (default: tag) — the prefix of the generated tag listing index pages. relative to the output directory.
  • template_dir (default: templates) — the directory that stores the template files. relative to blogcfile.

🌟 Posts listing

the [posts] section is a listing of the posts that will be included in the website. list them without the post prefix and without the extension — only the "slugs" should be used, okay? for example, with default settings, if the source of the post is content/post/foo.txt, the line you add to the [posts] section is foo. simple as that. ✨

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. same rules, bestie: 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. yes, each one. 🔥

the tags will also be provided to blogc as a MAKE_TAGS variable, which is a space-separated list of the tags — super useful for generating 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 🧚

here's what it looks like when it's all put together, bestie:

[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

iconic. no notes. 💅

💀 BUGS 💀

please report any issues to: https://github.com/blogc/blogc

(ngl, if you found a bug, tell them — they wanna know.)

🌈 AUTHOR 🌈

Rafael G. Martins <rafael@rafaelmartins.eng.br>

👀 SEE ALSO 👀

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

okay that's the whole page, bestie!! this one came from the blogc Manual, page BLOGCFILE(5), written by Rafael G. Martins, dated January 2025. love that for us. now go build something gorgeous 🫶💖✨

📦 where this page comes from