svbaelen/cowkit repository overview

⁠cowkit

⁠Comfortable features

Write and compose in markdown (or HTML) - convert to HTML⁠, LaTeX, and PDF.

• Convenient, though far from perfect⁠
• Can handle interconnected content structures (auto numbering of sections, tables, figures, etc.; .bib-based references and citations; among many other things. Also see example output⁠)
• Zero setup, no frameworks (requires only Docker⁠ with Pandoc⁠-based image)
• Fully customizable (styling, metadata, layout, ...)
• Focus on writing instead of compiling (file-watcher + auto build)

Built on top of Pandoc⁠ (file format converter), and inspired by this pandoc book template⁠.

⁠Get started

⁠Initialize new (example) project

docker run -u $(id -u):$(id -g) --rm -v "$(pwd):/app" -p 8000:8000 svbaelen/config --init

⁠Run

For default HTML output (and file watcher + HTTP server):

docker run -u $(id -u):$(id -g) --rm -v "$(pwd):/app" -p 8000:8000 svbaelen/cowkit

See the config section⁠ to find out where to put what. Other examples can be found here⁠.

You can specify a cowkit version with the image tag, e.g., cowkit:latest. For a non-docker runtime environment, see development⁠ section.

⁠CLI options

Check available options for the cowkit utility with --help:

docker run -u $(id -u):$(id -g) --rm -v "$(pwd):/app" -p 8000:8000 svbaelen/cowkit --help

⁠Update to latest version

docker image pull svbaelen/cowkit:latest

⁠Configuration

• config/config.yaml: main (output-independent) config
• config/<fmt>/config.yaml: output-specific config (can overwrite values set in main config.yaml).
• config/<fmt>/templates/<file>: templates related to specific output formats
• src/<file>.md: content files written in markdown. Every section, subsection, paragraph, figure, etc. can have a separate file. In the metadata section of each markdown file (between ---) you can add all kinds of metadata and config options supported by pandoc (and pandoc extensions), e.g., see here⁠.

Set (different) config and/or template files via cowkit CLI arguments⁠.

Additional functionality such as auto-reload can be disabled or extended via the header-includes section in the markdown metadata, e.g., see this example⁠.

⁠Examples

• See cowkit CLI examples here⁠
• For an example output document, check out this webpage⁠.

⁠More comfort

⁠Create alias

Create an alias to one or more relevant docker commands. Note that you can replace .bash_aliases with .bashrc or some other shell config file in your PATH:

# map to `cowkit`
CMD='docker run -u $(id -u):$(id -g) --rm -v "$(pwd):/app" -p 8000:8000 svbaelen/cowkit'
echo "alias cowkit='$CMD'" >> ~/.bash_aliases && source ~/.bash_aliases

Note that CLI arguments still work, e.g.:

• cowkit --init
• cowkit --format pdf --template /path/to/template

Naturally, these commands can be updated or removed anytime in ~/.bash_aliases.

⁠Speed up building

If re-running build process is too slow for you, open a ./config/<fmt>/config.yaml file and comment out stuff. Start with the Lua-based filters (which will skip bibliography rebuilds). If still too slow, uncomment sections/chapters etc.

⁠Caveats and known limitations

⁠General:

• Tested only on
  • Ubuntu 22.04

⁠CLI utility

• A fatal Pandoc error can crash the program (and file-watcher/builder), requiring the user to re-launch

⁠HTML output

• browser auto-reload after rebuild is based on LiveJS⁠, however, sometimes a manual refresh is necessary on the browser tab to re-initialize this script. This seems to occur on layout changes (not always). Need to inspect!