813 lines
27 KiB
HTML
813 lines
27 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.2.3</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>
|
||
<ul>
|
||
<li><a href="#workflow" id="toc-workflow">Workflow</a></li>
|
||
</ul></li>
|
||
<li><a href="#getting-started" id="toc-getting-started">Getting
|
||
Started</a>
|
||
<ul>
|
||
<li><a href="#clone-the-basic-book-builder"
|
||
id="toc-clone-the-basic-book-builder">Clone the Basic Book
|
||
Builder</a></li>
|
||
<li><a href="#setting-up-build-environment"
|
||
id="toc-setting-up-build-environment">Setting Up Build Environment</a>
|
||
<ul>
|
||
<li><a href="#non-deb-systems" id="toc-non-deb-systems">Non deb
|
||
systems</a></li>
|
||
</ul></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></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="#table-of-contents" id="toc-table-of-contents">Table of
|
||
Contents</a></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="#images" id="toc-images">Images</a></li>
|
||
<li><a href="#latex-equations" id="toc-latex-equations"><em>LaTeX</em>
|
||
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>
|
||
<li><a href="#advanced" id="toc-advanced">Advanced</a>
|
||
<ul>
|
||
<li><a href="#changing-fonts" id="toc-changing-fonts">Changing
|
||
Fonts</a></li>
|
||
<li><a href="#adding-filters" id="toc-adding-filters">Adding
|
||
Filters</a></li>
|
||
</ul></li>
|
||
</ul></li>
|
||
<li><a href="#design" id="toc-design">Design</a>
|
||
<ul>
|
||
<li><a href="#directory-structure"
|
||
id="toc-directory-structure">Directory Structure</a></li>
|
||
<li><a href="#configuration-files"
|
||
id="toc-configuration-files">Configuration Files</a>
|
||
<ul>
|
||
<li><a href="#pandoc-main-config" id="toc-pandoc-main-config">Pandoc
|
||
Main Config</a></li>
|
||
</ul></li>
|
||
<li><a href="#build-workflow" id="toc-build-workflow">Build
|
||
Workflow</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 <strong>basic book builder</strong> template is 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> + Makefile build process in conjunction Obsidian to
|
||
edit content and Zotero to manage citation, to generate multiple format
|
||
of the document including:</p>
|
||
<ul>
|
||
<li>PDF</li>
|
||
<li>HTML</li>
|
||
<li><em>LaTeX</em></li>
|
||
<li>Markdown</li>
|
||
<li>ODT</li>
|
||
<li>DOCX</li>
|
||
<li>Epub</li>
|
||
</ul>
|
||
<h3 id="workflow">Workflow</h3>
|
||
<ol type="1">
|
||
<li>Create a new project</li>
|
||
<li>Initialize <code>metadata.yaml</code> with title, copyright, author,
|
||
etc.</li>
|
||
<li>Customize <code>input-files:</code> in <code>pandoc.yaml</code></li>
|
||
<li>Edit <code>chapters</code> Markdown “conent” files using
|
||
Obidian</li>
|
||
<li>Build your document</li>
|
||
</ol>
|
||
<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="clone-the-basic-book-builder">Clone 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 (e.g Debian,
|
||
Ubuntu, Zorin). And this script will install several ATP packages on
|
||
your system.</p>
|
||
</div>
|
||
<div class="callout-danger">
|
||
<p><strong>Warning</strong></p>
|
||
<p> This script <strong>has not</strong> been widely tested across many
|
||
platforms</p>
|
||
</div>
|
||
<p>To initialize your systems build environment run:</p>
|
||
<div class="callout-cli">
|
||
<p><strong>Setup Build Environment</strong></p>
|
||
<pre><code>./scripts/setup-linux-deb.sh</code></pre>
|
||
</div>
|
||
<h3 id="non-deb-systems">Non deb systems</h3>
|
||
<p>For more information on setting up the build environment for your
|
||
system see: <strong>TBD: NEEDS DOCUMENTED</strong>.</p>
|
||
<h2 id="testing">Testing</h2>
|
||
<p>Once you have set up your build environment, you test by building the
|
||
<strong>basic book builder</strong>.</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>
|
||
<div class="callout-proposed">
|
||
<p><strong>Tip</strong></p>
|
||
<p> You do not want to edit your new project document in the
|
||
<code>basic-book-builder</code> directory. You will want to create a
|
||
<strong>new project</strong> for your document based on this
|
||
template.</p>
|
||
</div>
|
||
<div class="callout-cli">
|
||
<p><strong>Create a new project</strong></p>
|
||
<pre><code>./scripts/new-project.sh <NEW_PROJECT_DIR></code></pre>
|
||
</div>
|
||
<pre><code>cd <NEW_PROJECT_DIR></code></pre>
|
||
<p>Update your project configuration:</p>
|
||
<ol type="1">
|
||
<li>Edit: <code>metadata.yaml</code>, for title, author, etc</li>
|
||
<li>Edit: <code>templates/pandoc.yaml</code></li>
|
||
<li>Open: <code><NEW_PROJECT_DIR></code> with Obsidian, and edit
|
||
<code>chapters</code> documents.</li>
|
||
<li>Build: <code>make pdf</code></li>
|
||
</ol>
|
||
<div class="callout-warning">
|
||
<p><strong>Warning</strong></p>
|
||
<p> <code><NEW_PROJECT_DIR></code> should be outside of the
|
||
<strong>basic-book-builder</strong> directory</p>
|
||
</div>
|
||
<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>
|
||
<p>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.</p>
|
||
<h2 id="metadata">Metadata</h2>
|
||
<p>Metadata for the project is managed in <code>metadata.yaml</code>.
|
||
Edit this file to make <strong>global changes</strong> to variables for
|
||
your document. Definitions in <code>metadata.yaml</code> will propagate
|
||
to all format builds.</p>
|
||
<h2 id="front-matter">Front-matter</h2>
|
||
<p>Front-Matter documents control the Title Page, Metadata and other
|
||
pages before the Title of Contents. Front matter content is manged in
|
||
these files:</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>
|
||
<p>Unfortunately when you edit one, you need to edit the respective
|
||
changes to the other front-matter formats. ### Title Page</p>
|
||
<p>Edit the <strong>Front-matter</strong> files to modify the formatting
|
||
of the Title Page. You’ll need to modify the HTML / LaTex code.</p>
|
||
<h3 id="meta-data-page">Meta Data Page</h3>
|
||
<p>Edit the <strong>Front-matter</strong> files to modify the 2nd page
|
||
Metadata format and fields to display.</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</li>
|
||
</ul>
|
||
<h2 id="table-of-contents">Table of Contents</h2>
|
||
<p>The table of contents is auto generated. But can be disabled in
|
||
<code>template\pandoc.yaml</code> by setting: -
|
||
<code>toc: false</code></p>
|
||
<h2 id="chapters">Chapters</h2>
|
||
<p>Chapter Markdown source files are located in the
|
||
<code>chapters</code> directory. To edit which chapter files are
|
||
included the document:</p>
|
||
<ul>
|
||
<li>Edit the <code>input-file:</code> section of the
|
||
<code>template\pandoc.yaml</code></li>
|
||
</ul>
|
||
<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="images">Images</h2>
|
||
<p>You can use basic Markdown Images</p>
|
||
<pre><code></code></pre>
|
||
<figure>
|
||
<img src="lib/img/ACEPLogo.png" alt="ACEP" />
|
||
<figcaption aria-hidden="true">ACEP</figcaption>
|
||
</figure>
|
||
<h2 id="latex-equations"><em>LaTeX</em> Equations</h2>
|
||
<p>You can embed LaTeX equations directly in your Markdown pages.</p>
|
||
<h3 id="left-justified-inline">Left Justified / Inline</h3>
|
||
<p>To left justify <em>LaTex</em> surround the code inside single
|
||
<code>$</code>:</p>
|
||
<div class="callout-code">
|
||
<p><strong>Left Justified Equation</strong></p>
|
||
<pre><code>$x = \frac{1}{2}$</code></pre>
|
||
</div>
|
||
<p><span class="math inline">$x = \frac{1}{2}$</span></p>
|
||
<div class="callout-code">
|
||
<p><strong>Inline</strong></p>
|
||
<pre><code>Or inline, $x = \frac{1}{2}$, in a sentence.</code></pre>
|
||
</div>
|
||
<p>Or inline, <span class="math inline">$x = \frac{1}{2}$</span>, in a
|
||
sentence.</p>
|
||
<h3 id="centered">Centered</h3>
|
||
<p>To center justify <em>LaTex</em> surround the code inside double
|
||
<code>$$</code>:</p>
|
||
<div class="callout-code">
|
||
<p><strong>Centered Equation</strong></p>
|
||
<pre><code>$$x = \frac{1}{2}$$</code></pre>
|
||
</div>
|
||
<p><span class="math display">$$x = \frac{1}{2}$$</span></p>
|
||
<h2 id="custom-markdown">Custom Markdown</h2>
|
||
<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>[!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>
|
||
<h2 id="advanced">Advanced</h2>
|
||
<h3 id="changing-fonts">Changing Fonts</h3>
|
||
<p>It is possible to change fonts by editing
|
||
<code>templates/pandoc.yaml</code>, and
|
||
<code>templates\styles.css</code>, but you will have to make sure you
|
||
have the proper font’s installed on your system first.</p>
|
||
<h3 id="adding-filters">Adding Filters</h3>
|
||
<p>Custom filters can be created. This is complicated and typically
|
||
needs done in 3 places for:</p>
|
||
<ul>
|
||
<li>obsidian</li>
|
||
<li><em>LaTeX</em></li>
|
||
<li>HTML</li>
|
||
</ul>
|
||
<h1 id="design">Design</h1>
|
||
<h2 id="directory-structure">Directory Structure</h2>
|
||
<p>The <strong>basic-book-builder</strong> directory tree.</p>
|
||
<pre><code>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</code></pre>
|
||
<h2 id="configuration-files">Configuration Files</h2>
|
||
<p>The <strong>basic-book-builder</strong> configuration files, scripts,
|
||
and build files.</p>
|
||
<pre><code>../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
|
||
</code></pre>
|
||
<div class="callout-caution">
|
||
<p><strong>About conf</strong></p>
|
||
<p> NEVER: edit file directly in <code>conf</code>. They will be
|
||
overwritten by the build process. ### Metadata</p>
|
||
</div>
|
||
<p>Update the <code>metadata.yaml</code> file to globally configure your
|
||
document title and other metadata. Edit this file to control your
|
||
document title, author, etc.</p>
|
||
<h3 id="pandoc-main-config">Pandoc Main Config</h3>
|
||
<p>Update the <code>input-files:</code> section of
|
||
<code>templates/pandoc.yaml</code> to control what chapter source files
|
||
are in which order in your document.</p>
|
||
<pre><code># 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</code></pre>
|
||
<h2 id="build-workflow">Build Workflow</h2>
|
||
<p>For a PDF Build:</p>
|
||
<pre><code>make pdf</code></pre>
|
||
<p>will build dependencies on these file:</p>
|
||
<ol type="1">
|
||
<li>Makefile</li>
|
||
<li>conf/pandoc.yaml</li>
|
||
<li>conf/pdf.yaml</li>
|
||
<li>lib/zotero.bib</li>
|
||
<li>chapters/*.md</li>
|
||
</ol>
|
||
<p>NOTE: the <code>Makefile</code> will copy
|
||
<code>templates/*.yaml</code> to <code>conf/*.yaml</code>.
|
||
<strong>Never</strong> edit <code>conf/*</code>directly.</p>
|
||
<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>
|