basic-book-builder/build/html/basic-book-builder.html

548 lines
19 KiB
HTML
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang="">
<head>
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
<title>Basic Book Builder</title>
<style>
/* Default styles provided by pandoc.
** See https://pandoc.org/MANUAL.html#variables-for-html for config info.
*/
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
div.columns{display: flex; gap: min(4vw, 1.5em);}
div.column{flex: auto; overflow-x: auto;}
div.hanging-indent{margin-left: 1.5em; text-indent: -1.5em;}
/* The extra [class] is a hack that increases specificity enough to
override a similar rule in reveal.js */
ul.task-list[class]{list-style: none;}
ul.task-list li input[type="checkbox"] {
font-size: inherit;
width: 0.8em;
margin: 0 0.8em 0.2em -1.6em;
vertical-align: middle;
}
.display.math{display: block; text-align: center; margin: 0.5rem auto;}
/* CSS for citations */
div.csl-bib-body { }
div.csl-entry {
clear: both;
}
.hanging-indent div.csl-entry {
margin-left:2em;
text-indent:-2em;
}
div.csl-left-margin {
min-width:2em;
float:left;
}
div.csl-right-inline {
margin-left:2em;
padding-left:1em;
}
div.csl-indent {
margin-left: 2em;
} </style>
<link rel="stylesheet" href="conf/style.css" />
</head>
<body>
<div class="frontmatter">
<!-- Title Page -->
<h1 class="titlepage" style="margin-top:3em; font-size:2.4em; text-align:center;">Basic Book Builder</h1>
<h2 style="text-align:center; font-weight:normal;">A Pandoc template for building books, documents and articles</h2>
<div style="text-align:center; margin:2em 0;">
<img src="lib/img/UAF-ACEP.png" alt="Cover illustration" style="max-width:350px;">
</div>
<hr style="margin:3em 0;">
<!-- Metadata Page -->
<div style="text-align:left; margin-top:5em;">
<h2>Basic Book Builder</h2>
<i>A Pandoc template for building books, documents and articles</i>
<table style="margin-top:2em; width:50%; border-collapse:collapse;">
<tbody>
<tr><td style="font-weight:bold;">Author</td><td>John Haverlack</td></tr>
<tr><td style="font-weight:bold;">Version</td><td>1.1.0</td></tr>
<tr><td style="font-weight:bold;">Date</td><td>2026-02-04</td></tr>
<tr><td style="font-weight:bold;">Affiliation</td><td>Alaska Center for Energy and Power</td></tr>
<tr><td style="font-weight:bold;">Institution</td><td>University of Alaska Fairbanks</td></tr>
<tr><td style="font-weight:bold;">ISBN:</td><td>UNSPECIFIED</td></tr>
<tr><td style="font-weight:bold;">DOI:</td><td>UNSPECIFIED</td></tr>
<tr><td style="font-weight:bold;">Maturity</td><td>BETA</td></tr>
</tbody>
</table>
<p>Copyright © 2026 Alaska Center for Energy and Power</p>
<h3>Licensing</h3>
<h4>Open Source Edition (PDF and HTML)</h4>
<p>Licensed under the Creative Commons Attribution-NoDerivatives 4.0 International License
<ul>
<li>License: <a href="https://creativecommons.org/licenses/by-nd/4.0/">CC BY-ND 4.0</a></li>
</ul>
</p>
<!-- <h4>Commercial Edition (ebook and print)</h4>
<p>All Rights Reserved. No part of the EPUB or printed editions may be reproduced or redistributed without permission.</p> -->
</div>
<hr style="margin:4em 0;">
<!-- Image attribution + perception note (PDF analog) -->
<!-- <div style="width:100%; text-align:left; display:block; margin:1em 0;">
<h2>Cover Illustration</Code></h2>
</div>
<div style="max-width:40em; margin:auto;">
Cover illustration by <a href="$img-attribution-url$">$img-attribution$</a>.
</div> -->
</div>
<!-- <hr style="margin:4em 0;">
<div style="max-width:40em; margin:auto;">
<div style="width:100%; text-align:center; display:block; margin:1em 0; font-style: italic;">
This book is dedicated to ****.
</div>
</div>
<hr style="margin:4em 0;"> -->
<script>
window.MathJax = {
tex: { inlineMath: [['$', '$'], ['\\(', '\\)']] },
svg: { fontCache: 'global' }
};
</script>
<script src="lib/mathjax/tex-mml-chtml.js"></script>
<header id="title-block-header">
<h1 class="title">Basic Book Builder</h1>
</header>
<nav id="TOC" role="doc-toc">
<h2 id="toc-title">Contents</h2>
<ul>
<li><a href="#introduction" id="toc-introduction">Introduction</a></li>
<li><a href="#getting-started" id="toc-getting-started">Getting
Started</a>
<ul>
<li><a href="#cloning-the-basic-book-builder"
id="toc-cloning-the-basic-book-builder">Cloning the Basic Book
Builder</a></li>
<li><a href="#setting-up-build-environment"
id="toc-setting-up-build-environment">Setting Up Build
Environment</a></li>
<li><a href="#testing" id="toc-testing">Testing</a></li>
<li><a href="#creating-a-new-project"
id="toc-creating-a-new-project">Creating a New Project</a>
<ul>
<li><a href="#zotero-configuration-optional"
id="toc-zotero-configuration-optional">Zotero Configuration
(Optional)</a></li>
</ul></li>
</ul></li>
<li><a href="#usage" id="toc-usage">Usage</a>
<ul>
<li><a href="#editing-content" id="toc-editing-content">Editing
Content</a></li>
<li><a href="#building" id="toc-building">Building</a>
<ul>
<li><a href="#pdf" id="toc-pdf">PDF</a></li>
<li><a href="#html" id="toc-html">HTML</a></li>
<li><a href="#docx" id="toc-docx">DocX</a></li>
<li><a href="#odt" id="toc-odt">ODT</a></li>
<li><a href="#make-all" id="toc-make-all">Make All</a></li>
</ul></li>
<li><a href="#callouts" id="toc-callouts">Callouts</a></li>
</ul></li>
<li><a href="#appendix-a-build-environment-notes"
id="toc-appendix-a-build-environment-notes">Appendix A: Build
Environment Notes</a>
<ul>
<li><a href="#installing-pre-requisites"
id="toc-installing-pre-requisites">Installing Pre-Requisites</a>
<ul>
<li><a href="#required" id="toc-required">Required</a></li>
<li><a href="#optional" id="toc-optional">Optional</a></li>
</ul></li>
<li><a href="#editing-the-configuration"
id="toc-editing-the-configuration">Editing the Configuration</a></li>
</ul></li>
<li><a href="#glossary" id="toc-glossary">Glossary</a></li>
<li><a href="#bibliography" id="toc-bibliography">Bibliography</a></li>
</ul>
</nav>
<h1 id="introduction">Introduction</h1>
<p>This is a basic book (or article / document) builder template based
on a Pandoc<span class="citation" data-cites="PandocIndex">(<a
href="#ref-PandocIndex" role="doc-biblioref"><em>Pandoc - Index</em>,
n.d.</a>)</span> 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.</p>
<p>This <strong>basic book builder</strong><span class="citation"
data-cites="JehaverlackBasicbookbuilderPandoca">(<a
href="#ref-JehaverlackBasicbookbuilderPandoca"
role="doc-biblioref"><em>Jehaverlack/Basic-Book-Builder</em>,
n.d.</a>)</span> template has been curated by John Haverlack.<span
class="citation" data-cites="JohnHaverlackACEP">(<a
href="#ref-JohnHaverlackACEP" role="doc-biblioref"><em>John
<span>Haverlack</span> <span>ACEP</span></em>, n.d.</a>)</span></p>
<h1 id="getting-started">Getting Started</h1>
<h2 id="cloning-the-basic-book-builder">Cloning the Basic Book
Builder</h2>
<div class="callout-cli">
<p><strong>Clone the repository</strong></p>
<pre><code>git clone https://github.com/jehaverlack/basic-book-builder.git</code></pre>
</div>
<div class="callout-cli">
<p><strong>Navigate to the repo directory</strong></p>
<pre><code>cd basic-book-builder</code></pre>
</div>
<h2 id="setting-up-build-environment">Setting Up Build Environment</h2>
<div class="callout-caution">
<p><strong>~Debian Linux</strong></p>
<p> This script only support Debian based Linux system (Debian, Ubunutu,
Zorin, etc) This script has not been widely tested across platforms</p>
</div>
<div class="callout-cli">
<p><strong>Setup Build Environment</strong></p>
<pre><code>./scripts/setup-linux-deb.sh</code></pre>
</div>
<p>For more information on setting up the build environment for your
system see Appendix A.</p>
<h2 id="testing">Testing</h2>
<p>If you can build all format for the <strong>Basic Book Build</strong>
then you have a working build environment.</p>
<div class="callout-cli">
<p><strong>Testing Build Environment</strong></p>
<pre><code>make all</code></pre>
</div>
<h2 id="creating-a-new-project">Creating a New Project</h2>
<h3 id="zotero-configuration-optional">Zotero Configuration
(Optional)</h3>
<h1 id="usage">Usage</h1>
<h2 id="editing-content">Editing Content</h2>
<h2 id="building">Building</h2>
<h3 id="pdf">PDF</h3>
<pre><code>make pdf</code></pre>
<blockquote>
<p>NOTE: Building the PDF also builds the <strong>LaTeX</strong> version
of the book.</p>
</blockquote>
<h3 id="html">HTML</h3>
<pre><code>make html</code></pre>
<h3 id="docx">DocX</h3>
<pre><code>make docx</code></pre>
<blockquote>
<p>NOTE: DocX is a work in progress. Frontmatter and formatting need
work.</p>
</blockquote>
<h3 id="odt">ODT</h3>
<pre><code>make odt</code></pre>
<blockquote>
<p>NOTE: ODT is a work in progress. Frontmatter and formatting need
work.</p>
</blockquote>
<h3 id="make-all">Make All</h3>
<p>To build all supported formats</p>
<pre><code>make all</code></pre>
<h2 id="callouts">Callouts</h2>
<p>A few callout box styles have been added to easily highlight
content.</p>
<div class="callout-established">
<p><strong>Established Concept</strong></p>
<p> Einsteins Relativistic Dynamics Equations <span
class="math display"><em>E</em><sup>2</sup>=(<em>m</em><sub>0</sub> ⋅ <em>c</em><sup>2</sup>)<sup>2</sup>+(<em>p</em> ⋅ <em>c</em>)<sup>2</sup></span></p>
</div>
<div class="callout-proposed">
<p><strong>Proposed Concept</strong></p>
<p> With the speed of light, <span
class="math inline"><em>c</em>=1</span>: <span
class="math display"><em>E</em><sup>2</sup>=<em>m</em><sub>0</sub><sup>2</sup>+<em>p</em><sup>2</sup></span></p>
</div>
<div class="callout-speculative">
<p><strong>Speculative Concept</strong></p>
<p> With the speed of light, <span
class="math inline"><em>c</em>=1</span>: <span
class="math display"><em>E</em><sup>2</sup>=<em>m</em><sub>0</sub><sup>2</sup>+<em>p</em><sup>2</sup></span></p>
</div>
<div class="callout-caution">
<p><strong>Caution Note</strong></p>
<p> Beware of this section.</p>
</div>
<div class="callout-warning">
<p><strong>Warning Note</strong></p>
<p> Beware of this section.</p>
</div>
<div class="callout-danger">
<p><strong>Alerts</strong></p>
<p> Extreme Highlight</p>
</div>
<p>Appendix A</p>
<h1 id="appendix-a-build-environment-notes">Appendix A: Build
Environment Notes</h1>
<h2 id="installing-pre-requisites">Installing Pre-Requisites</h2>
<div class="callout-caution">
<p><strong>Not Cross-platform Tested</strong></p>
<p> For Debian / ZorinOS and likely Ubuntu based systems.</p>
</div>
<h3 id="required">Required</h3>
<h4 id="pandoc">Pandoc</h4>
<ul>
<li>https://pandoc.org/</li>
<li><a
href="https://github.com/jgm/pandoc/releases/tag/3.8.2.1">Download</a></li>
</ul>
<blockquote>
<p><code>sudo apt install https://github.com/jgm/pandoc/releases/download/3.8.2.1/pandoc-3.8.2.1-1-amd64.deb</code></p>
</blockquote>
<h4 id="code-editor">Code Editor</h4>
<div class="callout-established">
<p><strong>Code Editor</strong></p>
<p> <a href="https://vscodium.com/">VSCodium</a> is recommend for
privacy (telemetry/tracking) reasons - https://vscodium.com/</p>
</div>
<p>But any text editor will work. #### make</p>
<pre><code>sudo apt install make</code></pre>
<h4 id="jq-and-yq">jq and yq</h4>
<pre><code>sudo apt install jq yq</code></pre>
<h4 id="texlive">texlive</h4>
<blockquote>
<p><code>sudo apt install texlive texlive-xetex texlive-latex-extra texlive-fonts-recommended texlive-fonts-extra</code></p>
</blockquote>
<h4 id="mathjax">MathJax</h4>
<ul>
<li>https://www.mathjax.org/</li>
</ul>
<pre><code>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</code></pre>
<div class="callout-caution">
<p><strong>TODO</strong></p>
<p> This need to be rolled into a setup script.</p>
</div>
<h3 id="optional">Optional</h3>
<p>The following are not strictly requires to use this book builder
template.</p>
<h4 id="obsidian">Obsidian</h4>
<div class="callout-established">
<p><strong>Highly Recommended</strong></p>
<p> Editing book chapter content in Obsidian is a very productive means
for editing Markdown source content.</p>
</div>
<ul>
<li>https://obsidian.md/</li>
<li><a
href="https://github.com/obsidianmd/obsidian-releases/releases/download/v1.9.14/obsidian_1.9.14_amd64.deb">Deb
Package</a></li>
</ul>
<pre><code>sudo apt install https://github.com/obsidianmd/obsidian-releases/releases/download/v1.9.14/obsidian_1.9.14_amd64.deb</code></pre>
<h4 id="zotero">Zotero</h4>
<div class="callout-established">
<p><strong>Highly Recommended</strong></p>
<p> If you need to managed citations and references, Zotero integration
is highly recommended.</p>
</div>
<ul>
<li>https://www.zotero.org/</li>
</ul>
<pre><code>sudo cp ./scripts/deps/zotero.list /etc/apt/sources.list.d/</code></pre>
<pre><code>sudo apt update</code></pre>
<pre><code>sudo apt install zotero</code></pre>
<h5 id="better-bibtex-for-zotero">Better BibTex for Zotero</h5>
<p>Install the Better BibTex Plugin for Zotero - Zotero &gt; Tool &gt;
Plugins</p>
<h5 id="export-citations.bib">Export citations.bib</h5>
<ul>
<li>Zotero &gt; File &gt; Export Library &gt; Format: Better BibTeX</li>
<li><label><input type="checkbox" />Keep Updated</label></li>
<li><label><input type="checkbox" />Save to:
~/Documents/Lib/zotero.bib</label></li>
<li><label><input type="checkbox" />Symlink your
~/Documents/Lib/Citations.bib to
basic-book-builder/lib/zotero.bib</label></li>
</ul>
<h5 id="zotero-connector-browser-plugin">Zotero Connector Browser
Plugin</h5>
<ul>
<li>https://chromewebstore.google.com/detail/zotero-connector/ekhagklcjbdpajgpjgmbionohlpdbjgc</li>
</ul>
<p>Provides you the ability to auto add Web resources to your Zotero
citation database.</p>
<h4 id="lmodern">lmodern</h4>
<pre><code>sudo apt install lmodern</code></pre>
<h4 id="epubcheck">epubcheck</h4>
<pre><code>sudo apt install epubcheck</code></pre>
<h4 id="foliate">foliate</h4>
<p>An EPub Reader</p>
<ul>
<li>https://johnfactotum.github.io/foliate/</li>
</ul>
<pre><code>sudo apt install https://github.com/johnfactotum/foliate/releases/download/2.6.4/com.github.johnfactotum.foliate_2.6.4_all.deb</code></pre>
<h4 id="calibre">calibre</h4>
<p>An EPub Reader</p>
<ul>
<li>https://calibre-ebook.com</li>
</ul>
<pre><code>sudo apt install calibre</code></pre>
<h2 id="editing-the-configuration">Editing the Configuration</h2>
<h1 class="unnumbered" id="glossary">Glossary</h1>
<table>
<colgroup>
<col style="width: 17%" />
<col style="width: 82%" />
</colgroup>
<thead>
<tr>
<th>Term</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><strong>AST (Abstract Syntax Tree)</strong></td>
<td>Pandocs internal structured representation of a document. Lua
filters operate on the AST before rendering to a target format.</td>
</tr>
<tr>
<td><strong>Bibliography</strong></td>
<td>A <code>.bib</code> file (e.g., Zotero export) used by Pandoc with
<code>citeproc</code> to generate formatted citations and reference
lists.</td>
</tr>
<tr>
<td><strong>Callout</strong></td>
<td>A styled block (e.g., <code>[!warning]</code>) transformed by Lua
filters into format-specific output such as LaTeX environments or HTML
<code>&lt;div&gt;</code> elements.</td>
</tr>
<tr>
<td><strong>Defaults File (YAML)</strong></td>
<td>A Pandoc configuration file defining output format, filters,
metadata, and rendering options (e.g., <code>pdf.yaml</code>,
<code>html.yaml</code>).</td>
</tr>
<tr>
<td><strong>DOCX</strong></td>
<td>Microsoft Word document format generated by Pandoc; styling is
controlled via a <code>reference.docx</code> file.</td>
</tr>
<tr>
<td><strong>Filter (Lua)</strong></td>
<td>A script that modifies Pandocs AST before rendering. Used in this
workflow for callouts and other structural transformations.</td>
</tr>
<tr>
<td><strong>Frontmatter</strong></td>
<td>Format-specific content inserted before the main body (e.g.,
<code>frontmatter.tex</code>, <code>frontmatter.html</code>,
<code>frontmatter-docx.md</code>).</td>
</tr>
<tr>
<td><strong>HTML</strong></td>
<td>Web output format generated by Pandoc, typically styled via CSS and
supporting interactive features.</td>
</tr>
<tr>
<td><strong>LaTeX</strong></td>
<td>Typesetting system used for high-quality PDF generation via XeLaTeX
in this workflow.</td>
</tr>
<tr>
<td><strong>Lua Filter</strong></td>
<td>A lightweight scripting extension used by Pandoc to customize
document transformations programmatically.</td>
</tr>
<tr>
<td><strong>Makefile</strong></td>
<td>Automation script orchestrating the build pipeline for PDF, HTML,
DOCX, ODT, and Markdown outputs.</td>
</tr>
<tr>
<td><strong>Markdown</strong></td>
<td>Plain-text markup language serving as the source format for all
outputs in the workflow.</td>
</tr>
<tr>
<td><strong>Metadata</strong></td>
<td>Keyvalue pairs (e.g., <code>metadata.yaml</code>) defining title,
author, license, version, and other document variables.</td>
</tr>
<tr>
<td><strong>ODT</strong></td>
<td>OpenDocument Text format used by LibreOffice; similar to DOCX but
open-standard.</td>
</tr>
<tr>
<td><strong>Pandoc</strong></td>
<td>Universal document converter used to transform Markdown into PDF,
HTML, DOCX, ODT, EPUB, and more.</td>
</tr>
<tr>
<td><strong>PDF</strong></td>
<td>Portable Document Format output produced via Pandoc + XeLaTeX.</td>
</tr>
<tr>
<td><strong>Reference Document</strong></td>
<td>A DOCX or ODT file defining styles (fonts, headings, spacing) used
when generating Word/LibreOffice outputs.</td>
</tr>
<tr>
<td><strong>Resource Path</strong></td>
<td>Directories Pandoc searches for images, diagrams, and other assets
during rendering.</td>
</tr>
<tr>
<td><strong>Template</strong></td>
<td>A format-specific layout file (e.g., LaTeX template) used to control
document structure beyond styling.</td>
</tr>
<tr>
<td><strong>TOC (Table of Contents)</strong></td>
<td>Automatically generated navigation structure controlled by
<code>toc</code> and <code>toc-depth</code> options.</td>
</tr>
<tr>
<td><strong>XeLaTeX</strong></td>
<td>LaTeX engine used to generate PDFs with modern font support (via
<code>fontspec</code>).</td>
</tr>
<tr>
<td><strong>Zotero</strong></td>
<td>Reference manager used to generate <code>.bib</code> files for
citation processing with Pandoc.</td>
</tr>
</tbody>
</table>
<h1 class="unnumbered" id="bibliography">Bibliography</h1>
<div id="refs" class="references csl-bib-body hanging-indent"
role="list">
<div id="ref-JehaverlackBasicbookbuilderPandoca" class="csl-entry"
role="listitem">
<em>Jehaverlack/Basic-Book-Builder: <span>A Pandoc</span> Workflow for
Building <span>PDF</span>, <span>HTML</span>, <span>EPUB</span>, and
<span>LaTeX</span> Book Format.</em> n.d.
Https://github.com/jehaverlack/basic-book-builder.
</div>
<div id="ref-JohnHaverlackACEP" class="csl-entry" role="listitem">
<em>John <span>Haverlack</span> <span>ACEP</span></em>. n.d.
Https://www.uaf.edu/acep/about/our-team/john-haverlack.php.
</div>
<div id="ref-PandocIndex" class="csl-entry" role="listitem">
<em>Pandoc - Index</em>. n.d. Https://pandoc.org/.
</div>
</div>
</body>
</html>