bic

bic

Docs

bic is an opinionated and minimal static site generator—with a focus on blogs. View the demo or the source.

It uses Pandoc to convert plain Markdown files into HTML. They get templated {{Mustache}}-style with Mo. Sqids is used to generate IDs.

Basics

You get the (opinionated) basics of a static site/blog (read: opinionated):

For reproducible builds, I would recommend using bic with Docker: ghcr.io/pinjasaur/bic:latest

Essentially, mount your source directory to /src

docker run --rm -v "$PWD":/src ghcr.io/pinjasaur/bic:latest

to spit out a build directory with your generated site.

Alternatively, bic is available as a nix flake.

Follow the setting up flakes guide to enable it, then run

nix run github:Pinjasaur/bic --command bic .

to run bic in the current directory and spit out a build directory with your generated site.

Opinionated?

bic is strict where necessary to keep it opinionated with a lean scope.

Structure

For a fully-featured example, view the demo source code: https://github.com/Pinjasaur/bic-example

$ tree -F --dirsfirst
.
├── drafts/
│   └── 000-untitled.md
├── pages/
│   ├── about.md
├── posts/
│   ├── 998-foo-bar.md
│   └── 999-hello-world.md
├── static/
│   ├── css/
│   │   └── style.css
│   ├── img/
│   │   └── photo.jpg
│   └── js/
│       └── script.js
├── __feed.rss
├── __index.html
├── __tag.html
├── _footer.html
├── _head.html
├── _header.html
├── entry.html
├── feed.rss
├── index.html
├── page.html
├── robots.txt
├── sitemap.xml
├── tag.html
└── tags.html

Config

bic uses an .env pattern. This lets you configure required variables and add any extras that can be used within your templates. Talk about batteries included.

A .env file simply contains lines of KEY=value pairs. If you, for whatever reason, want to supply an environment variable at runtime and have it override your .env then use syntax such like:

ENV_VAR="${ENV_VAR:-default value}"

Not-100%-required but highly-recommended config:

Optional, change if needed:

Templating

Anything listed above or added additionally to a .env will be available globally within templates.

Some specific keys used within entries (posts or drafts) and pages (except where noted):

Drafts will have a draft key set. Likewise, posts will have a post key set.

Each entry in posts/*.md or drafts/*.md is rendered against an entry.html.

Each page in pages/*.md is rendered against a page.html.

index.html, feed.rss, and tag.html use a double-underscore-prefixed template partial of the same name e.g., {{__index}} from __index.html.

tags.html has access to an associative array of all_tags where the keys are the tags themselves and the values are the number of entries tagged by that tag.

sitemap.xml has access to an array of slugs with the slugs key.

Caveats

There is an order-of-operations for how files are built, as follows:

If you’re not careful, it’s possible you could overwrite an existing file e.g. pages/test.md and posts/999-test.md both map to /test.html. bic uses the Bash builtin noclobber e.g. set -o noclobber along with --interactive for cp to protect against these scenarios. This can be disabled by setting BIC_OVERWRITE. You’ve been warned.

Showcase

bic in the wild:

Support

bic is built & maintained by Paul.

ko-fi