slakkenhuis / pandoc.mk

Simple PDF & static website generation using `make`, `jq` and `pandoc`.

pandoc.mk

Plain text formats like Markdown and YAML are lightweight, understandable, maintainable in version control, and easy to modify. In the spirit of the UNIX philosophy, I glued a couple of common tools into pandoc.mk, a method for generating documents and static websites. The method encourages a radical separation of style from content: source text & data are converted to documents & images by a clean and transparent process, documented in a Makefile. It provides a common base and a consistent style for text projects — be it a thesis, a website, a resume…

The repository consists of two parts, either of which, I hope, may prove useful to someone:

1. Recipes for make. As of now, the core recipes call for pandoc, jq and find — and you could easily substitute or add ingredients.

2. Minimalist CSS stylesheets, compiled with sass. Change them to fit your tastes.

Usage

To use pandoc.mk, fill a directory with Markdown files like this:

---
title: An example.
make: [html, pdf]
style: article
---

Consider this graph: ![](graph.svg)

Then, create a Makefile with the following content:

include pandoc.mk pandoc-html.mk pandoc-pdf.mk

The first import will set PDF and HTML targets for corresponding files in the source directory. Documents without an appropriate value for make in the metadata will be ignored. The other imports will add default recipes to actually make those PDF and HTML targets.

Local resources that are linked to by the source documents, are also automatically targeted. If there is no recipe for a particular resource, add it to your Makefile. For the above example, that could be:

$(DEST)/graph.svg: $(SRC)/data.dat
    echo 'set terminal svg; set output "$@"; plot "$<"' | gnuplot

To start generating, run make. To remove obsoleted files of a previous run from the build/ directory, do make clean. With the proper configuration, the results can be uploaded with lftp or rsync by calling make upload.

See installation directions at the INSTALL.md. For configuration, consult the files in the include/ directory.

Similar software

Projects that take a similar bare-bones approach to website generation are simple-template and jqt. Should this be a bit primitive for your tastes, try static website generators such as zola, hugo, hakyll, jekyll, nanoc, yst or middleman.

License

To the greatest possible extent, I dedicate all content in this repository to the public domain (see UNLICENSE.md).