boh

boh is a simple static website generator. It scans a directory for markdown files, converts each file to HTML and writes the output to a mirrored path inside the _site directory.

It supports basic templating via envsubstr and a very simple YAML-like frontmatter, just simple key-value variables.

Requirements

Mandatory

• a markdown to html converter: cmark, Markdown.pl, markdown, and markdown-calibre executables are supported
• envsubst from GNU gettext package.

Optional

• inotifywait (optional) for boh watch
• python3 (optional) for boh serve

Basic usage

make install      # install into ~/.local/bin
boh new           # create basic site structure
echo '# ciao' > index.md 
boh build         # build website
boh serve         # serve

How it works

• every Markdown file found in the source directory is converted to HTML
• the output file keeps the same relative path inside _site
• YAML-like frontmatter can be used to define variables
• templates are processed using envsubst
• everything else (like copying assets) is left to the user

Structure

.
|_ _site/
|_ _layouts/
|_ boh.config
|_ index.md

Hacking

boh can be customized through boh.config file using hooks, plugin and overriding default functions.

Hooks

• boh_pre_build is run once before site build and cache generation
• boh_post_build is run once after site build and before cache regeneration
• boh_pre_build_page run before a page is built
• boh_post_build_page run after a page is built

Plugins

A plugin is a shell function exposed as boh subcommand. It can be useful for frequent task like: publish, create new pages from a specific template, assets management.

Example:

boh_command_publish() {
  boh_build
  # do some rclone stuff...  
}

boh_register_plugin "publish" 

boh_register_plugin makes boh publish listed in the help output.

Overriding default functions

Use unset to customize boh by overriding default functions, an example use case is customizing the markdown to html converter

unset boh_markdown
boh_markdown() {
  uvx --from markdown markdown_py -x fenced_code # replace current markdown parser with python markdown and load fenced code extension
}

Examples

• boh blog