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/cowkit --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!

Development

Build docker image

Example:

docker build -t svbaelen/cowkit:latest -t svbaelen/cowkit:v0.1.0 .

Push to repo:

docker push svbaelen/cowkit --all-tags

Build HTML

Native Pandoc:

pandoc --defaults=./config/config.yaml --defaults=./config/html/config.yaml \
  --template ./config/html/templates/default.html

With docker:

docker run --rm --volume "$(pwd):/data" \
  --user $(id -u):$(id -g)  pandoc/latex:latest \
  --defaults=./config/config.yaml \
  --defaults=./config/html/config.yaml --template ./config/html/templates/default.html

Build PDF

pandoc --defaults=./config/config.yaml --defaults=./config/pdf/config.yaml

With docker:

docker run --rm --volume "$(pwd):/data" \
  --user $(id -u):$(id -g)  pandoc/latex:latest \
  --defaults=./config/config.yaml   --defaults=./config/pdf/config.yaml

Acknowledgements

This project is built on, or inspired by:

• Markdown
• Pandoc
• Edward Tufte
• Pandoc crossref
• Other Pandoc-based projects:
  • Pandoc book template
  • Pandoc academic templates