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.2.3
Date	2026-02-05
Affiliation	Alaska Center for Energy and Power
Institution	University of Alaska Fairbanks
ISBN:	UNSPECIFIED
DOI:	UNSPECIFIED
Maturity	BETA

Copyright © 2026 Alaska Center for Energy and Power

Licensing

Open Source Edition (PDF and HTML)

Licensed under the Creative Commons Attribution-NoDerivatives 4.0 International License

• License: CC BY-ND 4.0

---

Introduction

This is a basic book builder template is based on a Pandoc(Pandoc - Index, n.d.) + Makefile build process in conjunction Obsidian to edit content and Zotero to manage citation, to generate multiple format of the document including:

• PDF
• HTML
• LaTeX
• Markdown
• ODT
• DOCX
• Epub

Workflow

1. Create a new project
2. Initialize metadata.yaml with title, copyright, author, etc.
3. Customize input-files: in pandoc.yaml
4. Edit chapters Markdown “conent” files using Obidian
5. Build your document

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

Getting Started

Clone the Basic Book Builder

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

cd basic-book-builder

Setting Up Build Environment

To initialize your systems build environment run:

./scripts/setup-linux-deb.sh

Non deb systems

For more information on setting up the build environment for your system see: TBD: NEEDS DOCUMENTED.

Testing

Once you have set up your build environment, you test by building the basic book builder.

make all

Creating a New Project

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

cd <NEW_PROJECT_DIR>

Update your project configuration:

1. Edit: metadata.yaml, for title, author, etc
2. Edit: templates/pandoc.yaml
3. Open: <NEW_PROJECT_DIR> with Obsidian, and edit chapters documents.
4. Build: make pdf

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

The basic book builder template integrates feature from many systems including Pandoc, MathJax, Obsidian, and Zotero. The following list covers these features from a functional point of view.

Metadata

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

Front-matter

Front-Matter documents control the Title Page, Metadata and other pages before the Title of Contents. Front matter content is manged in these files:

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

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. You’ll need to modify the HTML / LaTex code.

Meta Data Page

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

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

The table of contents is auto generated. But can be disabled in template\pandoc.yaml by setting: - toc: false

Chapters

Chapter Markdown source files are located in the chapters directory. To edit which chapter files are included the document:

• Edit the input-file: section of the template\pandoc.yaml

Appendixes

TBD

Glossary

TBD

Index

TBD

Markdown Indexes

TBD

Bibliography

TBD

Zotero Integration

TBD

Obsidian Citations

TBD

Images

You can use basic Markdown Images

![ACEP](lib/img/ACEPLogo.png)

LaTeX Equations

You can embed LaTeX equations directly in your Markdown pages.

Left Justified / Inline

To left justify LaTex surround the code inside single $:

$x = \frac{1}{2}$

$x = \frac{1}{2}$

Or inline, $x = \frac{1}{2}$, in a sentence.

Or inline, $x = \frac{1}{2}$, in a sentence.

Centered

To center justify LaTex surround the code inside double $$:

$$x = \frac{1}{2}$$

$$x = \frac{1}{2}$$

Custom Markdown

Call-outs

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

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

Will render:

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

Will render:

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

Will render:

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

Will render:

[!warning] Warning Note
Same as the Caution Box

Will render:

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

Will render:

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

Will render:

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

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

Will render:

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

Advanced

Changing Fonts

It is possible to change fonts by editing templates/pandoc.yaml, and templates\styles.css, but you will have to make sure you have the proper font’s installed on your system first.

Adding Filters

Custom filters can be created. This is complicated and typically needs done in 3 places for:

• obsidian
• LaTeX
• HTML

Design

Directory Structure

The basic-book-builder directory tree.

basic-book-builder
├── build
│   ├── docx
│   ├── html
│   │   ├── conf
│   │   └── lib
│   │       ├── diag
│   │       ├── img
│   │       └── mathjax
│   ├── latex
│   ├── odt
│   └── pdf
├── chapters
├── conf
├── filters
├── lib
│   ├── citations
│   ├── diag
│   ├── img
│   └── mathjax
├── scripts
│   └── tmp
└── templates

Configuration Files

The basic-book-builder configuration files, scripts, and build files.

../basic-book-builder
├── chapters
├── conf
├── filters
│   ├── callouts-html.lua
│   └── callouts.lua
├── lib
│   ├── diag
│   ├── img
│   └── zotero.bib
├── Makefile
├── metadata.yaml
├── scripts
│   ├── new-project.sh
│   ├── replace-metadata.sh
│   ├── setup-linux-deb.sh
│   └── tmp
└── templates
    ├── docx.yaml
    ├── epub_template.html
    ├── epub.yaml
    ├── frontmatter-docx.md
    ├── frontmatter.html
    ├── frontmatter-md.html
    ├── frontmatter.tex
    ├── header.tex
    ├── html.yaml
    ├── latex.yaml
    ├── markdown.yaml
    ├── odt.yaml
    ├── pandoc.yaml
    ├── pdf.yaml
    ├── style.css
    └── style_epub.css

Update the metadata.yaml file to globally configure your document title and other metadata. Edit this file to control your document title, author, etc.

Pandoc Main Config

Update the input-files: section of templates/pandoc.yaml to control what chapter source files are in which order in your document.

# pandoc.yaml
input-files:
  # - chapters/Preface.md
  - chapters/00_Introduction.md
  - chapters/01_Getting_Started.md
  - chapters/02_Usage.md
  - chapters/03_Features.md
  - chapters/Appendix.md
  - chapters/AppendixA.md
  # - chapters/AppendixB.md
  - chapters/Glossary.md
  - chapters/Index.md
  - chapters/Bibliography.md

Build Workflow

For a PDF Build:

make pdf

will build dependencies on these file:

1. Makefile
2. conf/pandoc.yaml
3. conf/pdf.yaml
4. lib/zotero.bib
5. chapters/*.md

NOTE: the Makefile will copy templates/*.yaml to conf/*.yaml. Never edit conf/*directly.

Glossary

Bibliography