Basic Book Builder

A Pandoc template for building books, documents and articles

Basic Book Builder

A Pandoc template for building books, documents 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

Editing Content

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

Callouts

A few callout box styles have been added to easily highlight content.

Established Concept

Einsteins Relativistic Dynamics Equations E² = (m₀ ⋅ c²)² + (p ⋅ c)²

Proposed Concept

With the speed of light, c = 1: E² = m₀² + p²

Speculative Concept

With the speed of light, c = 1: E² = m₀² + p²

Caution Note

Beware of this section.

Warning Note

Beware of this section.

Alerts

Extreme Highlight

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/.