Makefile to process all Asciidoctor files in a directory

by Christoph Stoettner
Read in about 2 min · (words)
asciidoctor make

Fountain pen and a notebook

Photo by Aaron Burden | Unsplash

I write most of my documents (blog posts, documentation, recipes and so on) with Asciidoctor. Everything is organized in Git repositories.

During GPN 19 (Gulaschprogrammiernacht) I showed how to build html and pdf with a Gitlab CI/CD pipeline. That’s quite handy, but lots of documents I build, I just need locally.

So today I played with WSL2 and a Makefile to build all Asciidoctor files in a directory.

Commandline to make pdf
asciidoctor-pdf source.adoc -o build/source.pdf

This builds a pdf in the directory build, but how can we create a pdf of some files?

Makefile
docs = $(wildcard *.adoc)            (1)
pdfs = $(docs:.adoc=.pdf)            (2)
all: $(pdfs)                         (3)
.PHONY: all

# Call asciidoctor to generate $@ from $^
%.pdf: %.adoc
	asciidoctor-pdf $^ -o build/$@     (4)
1Wildcard of all files with extension adoc in this directory
2Map .pdf instead of .adoc
3Run on all targets
4$@ is the PDF-File,
$^ is the Source

So just running make will create all documents converted in pdf.

Extend the Makefile

Create all documents converted to html and pdf in extra folders. Add commandline option variable.

Makefile
docs := $(wildcard *.adoc)
pdfs := $(docs:.adoc=.pdf)
htmls := $(docs:.adoc=.html)
options := -a toc -a toclevels="1"
all: html pdf
pdf: $(pdfs)
html: $(htmls)
.PHONY: all pdf html

# Call asciidoctor to generate $@ from $^
%.pdf: %.adoc
	asciidoctor-pdf $^ $(options) -o build/pdf/$@

%.html: %.adoc
	asciidoctor $^ $(options) -o build/html/$@

So now running make creates html and pdf targets.

makefile
Figure 1. Example with our recipe collection
makefile tree
Figure 2. Tree with source and target files

You can use this Makefile on Linux, Mac OS or Windows (with WSL) to convert a large scale of Asciidoctor files to your target.

Author

Christoph Stoettner

I work at Vegard IT GmbH as a senior consultant with a focus on collaboration software, Kubernetes, security and automation. I mainly deal with HCL Connections, WebSphere Application Server, Kubernetes, Ansible, Terraform and Linux.

Sometimes my daily work results in technical talks and blog articles, which you can follow here more or less regularly. You can find the presentations in the main menu under public speaking.

In my spare time I read a lot, test all kinds of technical software and gadgets and try to follow about 200 RSS feeds

This is my private blog, all opinions are my own.

           

Add a comment
Error
There was an error sending your comment, please try again.
Thank you!
Your comment has been submitted and will be published once it has been approved.

Your email address will not be published. Required fields are marked with *

Suggested Reading
Aaron Burden: Fountain pen and a notebook

Asciidoctor open links in new window

I write most of my documentation with Asciidoctor, so saving some keystrokes is important.

You can add window=_blank to links in your Asciidoctor source.

Read in about 1 min
Aaron Burden: Fountain pen and a notebook

Asciidoctor for Professional Looking Documentation

For GPN19 I prepared a second talk on Documentation with any Editor. The talk was based on a previous one from Froscon 13, but the pipeline tooling changed.

This time there was a technical issue during the recording and so there are only the slides available, but you can still watch the video of the Froscon talk: Froscon 13: Documentation with any Editor

Read in about 8 min
Aaron Burden: Fountain pen and a notebook

Gulasch Programmiernacht 2019 - #gpn19

Since thursday the gpn19 (Gulasch Programmiernacht) is taking place in Karlsruhe at ZKM. I’m happy that I got the chance to give two talks:

Read in about 1 min