Basic Book Builder

A Pandoc build process for books, docs and articles

Basic Book Builder

A Pandoc build process for books, docs and articles

Author	John Haverlack
Version	1.1.0
Date	2026-02-04
Affiliation	Alaska Center for Energy and Power
Institution	University of Alaska Fairbanks
ISBN:	UNSPECIFIED
DOI:	UNSPECIFIED
Maturity	BETA

Licensing

Open Source Edition (PDF and HTML)

Licensed under the Creative Commons Attribution-NoDerivatives 4.0 International License

License: CC BY-ND 4.0

Basic Book Builder

Introduction

This is a basic book (or article / document) builder template based on a Pandoc(Pandoc - Index, n.d.) build process in conjunction with a number of other tools to generate PDF, HTML, LaTex, Markdown, ODT, DOCX, and Epub book output formats from a single set Markdown source content , which can optionally be edited as an Obsidian vault.

This basic book builder(Jehaverlack/Basic-Book-Builder, n.d.) template has been curated by John Haverlack.(John Haverlack ACEP, n.d.)

Getting Started

Cloning the Basic Book Builder

Clone the repository

git clone https://github.com/jehaverlack/basic-book-builder.git

Navigate to the repo directory

cd basic-book-builder

Setting Up Build Environment

~Debian Linux

This script only support Debian based Linux system (Debian, Ubunutu, Zorin, etc) This script has not been widely tested across platforms

Setup Build Environment

./scripts/setup-linux-deb.sh

For more information on setting up the build environment for your system see Appendix A.

Testing

If you can build all format for the Basic Book Build then you have a working build environment.

Testing Build Environment

make all

Creating a New Project

Zotero Configuration (Optional)

Usage

Creating a Project

To create a new Project based on the Basic Book Builder template:

Run the new-project.sh script.

./scripts/new-project.sh <PATH_TO_PROJECT>

should be outside of the basic-book-builder directory

cd <PATH_TO_PROJECT>

Update:

metadata.yaml
templates/pandoc.yaml

Suggestion

Create a git repository to version control your new content.

Editing Content

Edit your source content Markdown under the chapters directory.

Optional

Open your <PATH_TO_PROJECT> directory as an Obsidian vault.
Edit your Markdown with Obsidian

Building

PDF

make pdf

NOTE: Building the PDF also builds the LaTeX version of the book.

HTML

make html

DocX

make docx

NOTE: DocX is a work in progress. Frontmatter and formatting need work.

ODT

make odt

NOTE: ODT is a work in progress. Frontmatter and formatting need work.

Make All

To build all supported formats

make all

Features

Metadata

Metadata for the project is managed in metadata.yaml. Edit this file to make global changes to variables for your document. Changes here will propagate to all format builds.

Front-matter

Front matter content is manged in:

templates/frontmatter.tex
templates/frontmatter.html
templates/frontmatter-md.html

Tip

Unfortunately when you edit one, you need to edit the respective changes to the other front-matter formats. ### Title Page

Edit the Front-matter files to modify the formatting of the Title Page.

Tip

You’ll need to modify the HTML / LaTex.

Meta Data Page

Edit the Front-matter files to modify the 2nd page Metadata format.

Cover Illustration

Edit the Front-matter files to optionally un-comment the Cover Art Acknowledgement.

This is disabled by default

Dedication

Edit the Front-matter files to modify un-comment the Book Dedication.

This is disabled by default ## Table of Contents

Chapters

Chapter Markdown source files are located in the chapters directory. Edit the template\pandoc.yaml file to control which chapter markdown files are in what order.

Appendixes

TBD

Glossary

TBD

Index

TBD

Markdown Indexes

TBD

Bibliography

TBD

Zotero Integration

TBD

Obsidian Citations

TBD

Mathjax Equations

TBD

Left Justified / Inline

TBD

Centered

TBD

Custom Markdown

TBD

Call-outs

A few call-out box styles have been custom added to easily highlight certain types of content.

Markdown Example

[!established] Green Call-out Title
A green box

Will render:

Green Call-out Title

A green box

Markdown Example

[!proposed] Blue Call-out Title
A blue box

Will render:

Blue Call-out Title

A blue box

Markdown Example

[!info] Info Box
Same as a blue box

Will render:

Info Box

Same as a blue box

Markdown Example

[!speculative] Purple Call-out Title
A purple box

Will render:

Purple Call-out Title

A purple box

Markdown Example

[!caution] Caution Note
Beware of this section.  AKA a orange box.

Will render:

Caution Note

Beware of this section. AKA a orange box.

Markdown Example

[!warning] Warning Note
Same as the Caution Box

Will render:

Warning Note

Same as the Caution Box

Markdown Example

[!danger] Alert
A slightly stronger warning.  AKA a red box.

Will render:

Alert

A slightly stronger warning. AKA a red box.

Markdown Example

[!code] Code Block
'''
if [ true ]; do
  echo "The Cow Jumps over the Moon"
fi
'''

Will render:

Code Block

if [ true ]; do
  echo "The Cow Jumps over the Moon"
fi

Markdown Example

[!cli] Command line
A command line example
'''
$ ls
build  chapters  conf  filters  lib  LICENSE.md  Makefile  metadata.yaml  >README.md  scripts  templates
'''

Will render:

Command line

A command line example

$ ls
build  chapters  conf  filters  lib  LICENSE.md  Makefile  metadata.yaml  README.md  scripts  templates

Appendix A

Appendix A: Build Environment Notes

Installing Pre-Requisites

Not Cross-platform Tested

For Debian / ZorinOS and likely Ubuntu based systems.

Required

Pandoc

https://pandoc.org/
Download

sudo apt install https://github.com/jgm/pandoc/releases/download/3.8.2.1/pandoc-3.8.2.1-1-amd64.deb

Code Editor

Code Editor

VSCodium is recommend for privacy (telemetry/tracking) reasons - https://vscodium.com/

But any text editor will work. #### make

sudo apt install make

jq and yq

sudo apt install jq yq

texlive

sudo apt install texlive texlive-xetex texlive-latex-extra texlive-fonts-recommended texlive-fonts-extra

MathJax

https://www.mathjax.org/

wget https://registry.npmjs.org/mathjax/-/mathjax-3.2.2.tgz
tar xzf mathjax-3.2.2.tgz
mv package/es5/* lib/mathjax
rm -rf package mathjax-3.2.2.tgz

TODO

This need to be rolled into a setup script.

Optional

The following are not strictly requires to use this book builder template.

Obsidian

Highly Recommended

Editing book chapter content in Obsidian is a very productive means for editing Markdown source content.

https://obsidian.md/
Deb Package

sudo apt install https://github.com/obsidianmd/obsidian-releases/releases/download/v1.9.14/obsidian_1.9.14_amd64.deb

Zotero

Highly Recommended

If you need to managed citations and references, Zotero integration is highly recommended.

https://www.zotero.org/

sudo cp ./scripts/deps/zotero.list /etc/apt/sources.list.d/

sudo apt update

sudo apt install zotero

Better BibTex for Zotero

Install the Better BibTex Plugin for Zotero - Zotero > Tool > Plugins

Export citations.bib

Zotero > File > Export Library > Format: Better BibTeX
Keep Updated
Save to: ~/Documents/Lib/zotero.bib
Symlink your ~/Documents/Lib/Citations.bib to basic-book-builder/lib/zotero.bib

Zotero Connector Browser Plugin

https://chromewebstore.google.com/detail/zotero-connector/ekhagklcjbdpajgpjgmbionohlpdbjgc

Provides you the ability to auto add Web resources to your Zotero citation database.

lmodern

sudo apt install lmodern

epubcheck

sudo apt install epubcheck

foliate

An EPub Reader

https://johnfactotum.github.io/foliate/

sudo apt install https://github.com/johnfactotum/foliate/releases/download/2.6.4/com.github.johnfactotum.foliate_2.6.4_all.deb

calibre

An EPub Reader

https://calibre-ebook.com

sudo apt install calibre

Editing the Configuration

Glossary

Term	Description
AST (Abstract Syntax Tree)	Pandoc’s internal structured representation of a document. Lua filters operate on the AST before rendering to a target format.
Bibliography	A `.bib` file (e.g., Zotero export) used by Pandoc with `citeproc` to generate formatted citations and reference lists.
Callout	A styled block (e.g., `[!warning]`) transformed by Lua filters into format-specific output such as LaTeX environments or HTML `<div>` elements.
Defaults File (YAML)	A Pandoc configuration file defining output format, filters, metadata, and rendering options (e.g., `pdf.yaml`, `html.yaml`).
DOCX	Microsoft Word document format generated by Pandoc; styling is controlled via a `reference.docx` file.
Filter (Lua)	A script that modifies Pandoc’s AST before rendering. Used in this workflow for callouts and other structural transformations.
Frontmatter	Format-specific content inserted before the main body (e.g., `frontmatter.tex`, `frontmatter.html`, `frontmatter-docx.md`).
HTML	Web output format generated by Pandoc, typically styled via CSS and supporting interactive features.
LaTeX	Typesetting system used for high-quality PDF generation via XeLaTeX in this workflow.
Lua Filter	A lightweight scripting extension used by Pandoc to customize document transformations programmatically.
Makefile	Automation script orchestrating the build pipeline for PDF, HTML, DOCX, ODT, and Markdown outputs.
Markdown	Plain-text markup language serving as the source format for all outputs in the workflow.
Metadata	Key–value pairs (e.g., `metadata.yaml`) defining title, author, license, version, and other document variables.
ODT	OpenDocument Text format used by LibreOffice; similar to DOCX but open-standard.
Pandoc	Universal document converter used to transform Markdown into PDF, HTML, DOCX, ODT, EPUB, and more.
PDF	Portable Document Format output produced via Pandoc + XeLaTeX.
Reference Document	A DOCX or ODT file defining styles (fonts, headings, spacing) used when generating Word/LibreOffice outputs.
Resource Path	Directories Pandoc searches for images, diagrams, and other assets during rendering.
Template	A format-specific layout file (e.g., LaTeX template) used to control document structure beyond styling.
TOC (Table of Contents)	Automatically generated navigation structure controlled by `toc` and `toc-depth` options.
XeLaTeX	LaTeX engine used to generate PDFs with modern font support (via `fontspec`).
Zotero	Reference manager used to generate `.bib` files for citation processing with Pandoc.

Bibliography

Jehaverlack/Basic-Book-Builder: A Pandoc Workflow for Building PDF, HTML, EPUB, and LaTeX Book Format. n.d. Https://github.com/jehaverlack/basic-book-builder.

John Haverlack ACEP. n.d. Https://www.uaf.edu/acep/about/our-team/john-haverlack.php.

Pandoc - Index. n.d. Https://pandoc.org/.