764 lines
26 KiB
HTML
764 lines
26 KiB
HTML
<!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 build process for books, docs 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 build process for books, docs 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-05</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="#creating-a-project" id="toc-creating-a-project">Creating a
|
||
Project</a></li>
|
||
<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>
|
||
</ul></li>
|
||
<li><a href="#features" id="toc-features">Features</a>
|
||
<ul>
|
||
<li><a href="#metadata" id="toc-metadata">Metadata</a></li>
|
||
<li><a href="#front-matter" id="toc-front-matter">Front-matter</a>
|
||
<ul>
|
||
<li><a href="#meta-data-page" id="toc-meta-data-page">Meta Data
|
||
Page</a></li>
|
||
<li><a href="#cover-illustration" id="toc-cover-illustration">Cover
|
||
Illustration</a></li>
|
||
<li><a href="#dedication" id="toc-dedication">Dedication</a></li>
|
||
</ul></li>
|
||
<li><a href="#chapters" id="toc-chapters">Chapters</a></li>
|
||
<li><a href="#appendixes" id="toc-appendixes">Appendixes</a></li>
|
||
<li><a href="#glossary" id="toc-glossary">Glossary</a></li>
|
||
<li><a href="#index" id="toc-index">Index</a>
|
||
<ul>
|
||
<li><a href="#markdown-indexes" id="toc-markdown-indexes">Markdown
|
||
Indexes</a></li>
|
||
</ul></li>
|
||
<li><a href="#bibliography" id="toc-bibliography">Bibliography</a>
|
||
<ul>
|
||
<li><a href="#zotero-integration" id="toc-zotero-integration">Zotero
|
||
Integration</a></li>
|
||
<li><a href="#obsidian-citations" id="toc-obsidian-citations">Obsidian
|
||
Citations</a></li>
|
||
</ul></li>
|
||
<li><a href="#mathjax-equations" id="toc-mathjax-equations">Mathjax
|
||
Equations</a>
|
||
<ul>
|
||
<li><a href="#left-justified-inline" id="toc-left-justified-inline">Left
|
||
Justified / Inline</a></li>
|
||
<li><a href="#centered" id="toc-centered">Centered</a></li>
|
||
</ul></li>
|
||
<li><a href="#custom-markdown" id="toc-custom-markdown">Custom
|
||
Markdown</a>
|
||
<ul>
|
||
<li><a href="#call-outs" id="toc-call-outs">Call-outs</a></li>
|
||
</ul></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-1" id="toc-glossary-1">Glossary</a></li>
|
||
<li><a href="#bibliography-1"
|
||
id="toc-bibliography-1">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="creating-a-project">Creating a Project</h2>
|
||
<p>To create a new Project based on the Basic Book Builder template:</p>
|
||
<ol type="1">
|
||
<li>Run the new-project.sh script.</li>
|
||
</ol>
|
||
<pre><code>./scripts/new-project.sh <PATH_TO_PROJECT></code></pre>
|
||
<ul>
|
||
<li><PATH_TO_PROJECT> should be outside of the
|
||
<strong>basic-book-builder</strong> directory</li>
|
||
</ul>
|
||
<pre><code>cd <PATH_TO_PROJECT></code></pre>
|
||
<p>Update:</p>
|
||
<ol type="1">
|
||
<li><code>metadata.yaml</code></li>
|
||
<li><code>templates/pandoc.yaml</code></li>
|
||
</ol>
|
||
<div class="callout-info">
|
||
<p><strong>Suggestion</strong></p>
|
||
<p> Create a git repository to version control your new
|
||
<PATH_TO_PROJECT> content.</p>
|
||
</div>
|
||
<h2 id="editing-content">Editing Content</h2>
|
||
<p>Edit your source content Markdown under the <code>chapters</code>
|
||
directory.</p>
|
||
<p><strong>Optional</strong></p>
|
||
<ul>
|
||
<li>Open your <code><PATH_TO_PROJECT></code> directory as an
|
||
Obsidian vault.</li>
|
||
<li>Edit your Markdown with Obsidian</li>
|
||
</ul>
|
||
<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>
|
||
<h1 id="features">Features</h1>
|
||
<h2 id="metadata">Metadata</h2>
|
||
<p>Metadata for the project is managed in <code>metadata.yaml</code>.
|
||
Edit this file to make global changes to variables for your document.
|
||
Changes here will propagate to all format builds.</p>
|
||
<h2 id="front-matter">Front-matter</h2>
|
||
<p>Front matter content is manged in:</p>
|
||
<ul>
|
||
<li><code>templates/frontmatter.tex</code></li>
|
||
<li><code>templates/frontmatter.html</code></li>
|
||
<li><code>templates/frontmatter-md.html</code></li>
|
||
</ul>
|
||
<div class="callout-caution">
|
||
<p><strong>Tip</strong></p>
|
||
<p> Unfortunately when you edit one, you need to edit the respective
|
||
changes to the other front-matter formats. ### Title Page</p>
|
||
</div>
|
||
<p>Edit the <strong>Front-matter</strong> files to modify the formatting
|
||
of the Title Page.</p>
|
||
<div class="callout-caution">
|
||
<p><strong>Tip</strong></p>
|
||
<p> You’ll need to modify the HTML / LaTex.</p>
|
||
</div>
|
||
<h3 id="meta-data-page">Meta Data Page</h3>
|
||
<p>Edit the <strong>Front-matter</strong> files to modify the 2nd page
|
||
Metadata format.</p>
|
||
<h3 id="cover-illustration">Cover Illustration</h3>
|
||
<p>Edit the <strong>Front-matter</strong> files to optionally un-comment
|
||
the Cover Art Acknowledgement.</p>
|
||
<ul>
|
||
<li>This is disabled by default</li>
|
||
</ul>
|
||
<h3 id="dedication">Dedication</h3>
|
||
<p>Edit the <strong>Front-matter</strong> files to modify un-comment the
|
||
Book Dedication.</p>
|
||
<ul>
|
||
<li>This is disabled by default ## Table of Contents</li>
|
||
</ul>
|
||
<h2 id="chapters">Chapters</h2>
|
||
<p>Chapter Markdown source files are located in the
|
||
<code>chapters</code> directory. Edit the
|
||
<code>template\pandoc.yaml</code> file to control which chapter markdown
|
||
files are in what order.</p>
|
||
<h2 id="appendixes">Appendixes</h2>
|
||
<p>TBD</p>
|
||
<h2 id="glossary">Glossary</h2>
|
||
<p>TBD</p>
|
||
<h2 id="index">Index</h2>
|
||
<p>TBD</p>
|
||
<h3 id="markdown-indexes">Markdown Indexes</h3>
|
||
<p>TBD</p>
|
||
<h2 id="bibliography">Bibliography</h2>
|
||
<p>TBD</p>
|
||
<h3 id="zotero-integration">Zotero Integration</h3>
|
||
<p>TBD</p>
|
||
<h3 id="obsidian-citations">Obsidian Citations</h3>
|
||
<p>TBD</p>
|
||
<h2 id="mathjax-equations">Mathjax Equations</h2>
|
||
<p>TBD</p>
|
||
<h3 id="left-justified-inline">Left Justified / Inline</h3>
|
||
<p>TBD</p>
|
||
<h3 id="centered">Centered</h3>
|
||
<p>TBD</p>
|
||
<h2 id="custom-markdown">Custom Markdown</h2>
|
||
<p>TBD</p>
|
||
<h3 id="call-outs">Call-outs</h3>
|
||
<p>A few call-out box styles have been custom added to easily highlight
|
||
certain types of content.</p>
|
||
<div class="callout-code">
|
||
<p><strong>Markdown Example</strong></p>
|
||
<pre><code>[!established] Green Call-out Title
|
||
A green box</code></pre>
|
||
</div>
|
||
<p>Will render:</p>
|
||
<div class="callout-established">
|
||
<p><strong>Green Call-out Title</strong></p>
|
||
<p> A green box</p>
|
||
</div>
|
||
<hr />
|
||
<div class="callout-code">
|
||
<p><strong>Markdown Example</strong></p>
|
||
<pre><code>[!proposed] Blue Call-out Title
|
||
A blue box</code></pre>
|
||
</div>
|
||
<p>Will render:</p>
|
||
<div class="callout-proposed">
|
||
<p><strong>Blue Call-out Title</strong></p>
|
||
<p> A blue box</p>
|
||
</div>
|
||
<hr />
|
||
<div class="callout-code">
|
||
<p><strong>Markdown Example</strong></p>
|
||
<pre><code>[!info] Info Box
|
||
Same as a blue box</code></pre>
|
||
</div>
|
||
<p>Will render:</p>
|
||
<div class="callout-info">
|
||
<p><strong>Info Box</strong></p>
|
||
<p> Same as a blue box</p>
|
||
</div>
|
||
<hr />
|
||
<div class="callout-code">
|
||
<p><strong>Markdown Example</strong></p>
|
||
<pre><code>[!speculative] Purple Call-out Title
|
||
A purple box</code></pre>
|
||
</div>
|
||
<p>Will render:</p>
|
||
<div class="callout-speculative">
|
||
<p><strong>Purple Call-out Title</strong></p>
|
||
<p> A purple box</p>
|
||
</div>
|
||
<hr />
|
||
<div class="callout-code">
|
||
<p><strong>Markdown Example</strong></p>
|
||
<pre><code>[!caution] Caution Note
|
||
Beware of this section. AKA a orange box.</code></pre>
|
||
</div>
|
||
<p>Will render:</p>
|
||
<div class="callout-caution">
|
||
<p><strong>Caution Note</strong></p>
|
||
<p> Beware of this section. AKA a orange box.</p>
|
||
</div>
|
||
<hr />
|
||
<div class="callout-code">
|
||
<p><strong>Markdown Example</strong></p>
|
||
<pre><code>[!warning] Warning Note
|
||
Same as the Caution Box</code></pre>
|
||
</div>
|
||
<p>Will render:</p>
|
||
<div class="callout-warning">
|
||
<p><strong>Warning Note</strong></p>
|
||
<p> Same as the Caution Box</p>
|
||
</div>
|
||
<hr />
|
||
<div class="callout-code">
|
||
<p><strong>Markdown Example</strong></p>
|
||
<pre><code>[!danger] Alert
|
||
A slightly stronger warning. AKA a red box.</code></pre>
|
||
</div>
|
||
<p>Will render:</p>
|
||
<div class="callout-danger">
|
||
<p><strong>Alert</strong></p>
|
||
<p> A slightly stronger warning. AKA a red box.</p>
|
||
</div>
|
||
<hr />
|
||
<div class="callout-code">
|
||
<p><strong>Markdown Example</strong></p>
|
||
<pre><code>[!code] Code Block
|
||
'''
|
||
if [ true ]; do
|
||
echo "The Cow Jumps over the Moon"
|
||
fi
|
||
'''</code></pre>
|
||
</div>
|
||
<p>Will render:</p>
|
||
<div class="callout-code">
|
||
<p><strong>Code Block</strong></p>
|
||
<pre><code>if [ true ]; do
|
||
echo "The Cow Jumps over the Moon"
|
||
fi</code></pre>
|
||
</div>
|
||
<hr />
|
||
<div class="callout-code">
|
||
<p><strong>Markdown Example</strong></p>
|
||
<pre><code>[!cli] Command line
|
||
A command line example
|
||
'''
|
||
$ ls
|
||
build chapters conf filters lib LICENSE.md Makefile metadata.yaml >README.md scripts templates
|
||
'''</code></pre>
|
||
</div>
|
||
<p>Will render:</p>
|
||
<div class="callout-cli">
|
||
<p><strong>Command line</strong></p>
|
||
<p> A command line example</p>
|
||
<pre><code>$ ls
|
||
build chapters conf filters lib LICENSE.md Makefile metadata.yaml README.md scripts templates</code></pre>
|
||
</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 > Tool >
|
||
Plugins</p>
|
||
<h5 id="export-citations.bib">Export citations.bib</h5>
|
||
<ul>
|
||
<li>Zotero > File > Export Library > 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-1">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>Pandoc’s 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><div></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 Pandoc’s 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>Key–value 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-1">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>
|