1213 lines
30 KiB
TeX
1213 lines
30 KiB
TeX
% Options for packages loaded elsewhere
|
|
\PassOptionsToPackage{unicode}{hyperref}
|
|
\PassOptionsToPackage{hyphens}{url}
|
|
\PassOptionsToPackage{dvipsnames,svgnames,x11names}{xcolor}
|
|
\documentclass[
|
|
12pt,
|
|
openany]{book}
|
|
\usepackage{xcolor}
|
|
\usepackage[margin=1in]{geometry}
|
|
\usepackage{amsmath,amssymb}
|
|
\setcounter{secnumdepth}{5}
|
|
\usepackage{iftex}
|
|
\ifPDFTeX
|
|
\usepackage[T1]{fontenc}
|
|
\usepackage[utf8]{inputenc}
|
|
\usepackage{textcomp} % provide euro and other symbols
|
|
\else % if luatex or xetex
|
|
\usepackage{unicode-math} % this also loads fontspec
|
|
\defaultfontfeatures{Scale=MatchLowercase}
|
|
\defaultfontfeatures[\rmfamily]{Ligatures=TeX,Scale=1}
|
|
\fi
|
|
\usepackage{lmodern}
|
|
\ifPDFTeX\else
|
|
% xetex/luatex font selection
|
|
\setmainfont[]{TeX Gyre Termes}
|
|
\setsansfont[]{TeX Gyre Heros}
|
|
\setmonofont[]{TeX Gyre Cursor}
|
|
\fi
|
|
% Use upquote if available, for straight quotes in verbatim environments
|
|
\IfFileExists{upquote.sty}{\usepackage{upquote}}{}
|
|
\IfFileExists{microtype.sty}{% use microtype if available
|
|
\usepackage[]{microtype}
|
|
\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
|
|
}{}
|
|
\makeatletter
|
|
\@ifundefined{KOMAClassName}{% if non-KOMA class
|
|
\IfFileExists{parskip.sty}{%
|
|
\usepackage{parskip}
|
|
}{% else
|
|
\setlength{\parindent}{0pt}
|
|
\setlength{\parskip}{6pt plus 2pt minus 1pt}}
|
|
}{% if KOMA class
|
|
\KOMAoptions{parskip=half}}
|
|
\makeatother
|
|
\usepackage{longtable,booktabs,array}
|
|
\newcounter{none} % for unnumbered tables
|
|
\usepackage{calc} % for calculating minipage widths
|
|
% Correct order of tables after \paragraph or \subparagraph
|
|
\usepackage{etoolbox}
|
|
\makeatletter
|
|
\patchcmd\longtable{\par}{\if@noskipsec\mbox{}\fi\par}{}{}
|
|
\makeatother
|
|
% Allow footnotes in longtable head/foot
|
|
\IfFileExists{footnotehyper.sty}{\usepackage{footnotehyper}}{\usepackage{footnote}}
|
|
\makesavenoteenv{longtable}
|
|
\usepackage{graphicx}
|
|
\makeatletter
|
|
\newsavebox\pandoc@box
|
|
\newcommand*\pandocbounded[1]{% scales image to fit in text height/width
|
|
\sbox\pandoc@box{#1}%
|
|
\Gscale@div\@tempa{\textheight}{\dimexpr\ht\pandoc@box+\dp\pandoc@box\relax}%
|
|
\Gscale@div\@tempb{\linewidth}{\wd\pandoc@box}%
|
|
\ifdim\@tempb\p@<\@tempa\p@\let\@tempa\@tempb\fi% select the smaller of both
|
|
\ifdim\@tempa\p@<\p@\scalebox{\@tempa}{\usebox\pandoc@box}%
|
|
\else\usebox{\pandoc@box}%
|
|
\fi%
|
|
}
|
|
% Set default figure placement to htbp
|
|
\def\fps@figure{htbp}
|
|
\makeatother
|
|
% definitions for citeproc citations
|
|
\NewDocumentCommand\citeproctext{}{}
|
|
\NewDocumentCommand\citeproc{mm}{%
|
|
\begingroup\def\citeproctext{#2}\cite{#1}\endgroup}
|
|
\makeatletter
|
|
% allow citations to break across lines
|
|
\let\@cite@ofmt\@firstofone
|
|
% avoid brackets around text for \cite:
|
|
\def\@biblabel#1{}
|
|
\def\@cite#1#2{{#1\if@tempswa , #2\fi}}
|
|
\makeatother
|
|
\newlength{\cslhangindent}
|
|
\setlength{\cslhangindent}{1.5em}
|
|
\newlength{\csllabelwidth}
|
|
\setlength{\csllabelwidth}{3em}
|
|
\newenvironment{CSLReferences}[2] % #1 hanging-indent, #2 entry-spacing
|
|
{\begin{list}{}{%
|
|
\setlength{\itemindent}{0pt}
|
|
\setlength{\leftmargin}{0pt}
|
|
\setlength{\parsep}{0pt}
|
|
% turn on hanging indent if param 1 is 1
|
|
\ifodd #1
|
|
\setlength{\leftmargin}{\cslhangindent}
|
|
\setlength{\itemindent}{-1\cslhangindent}
|
|
\fi
|
|
% set entry spacing
|
|
\setlength{\itemsep}{#2\baselineskip}}}
|
|
{\end{list}}
|
|
\usepackage{calc}
|
|
\newcommand{\CSLBlock}[1]{\hfill\break\parbox[t]{\linewidth}{\strut\ignorespaces#1\strut}}
|
|
\newcommand{\CSLLeftMargin}[1]{\parbox[t]{\csllabelwidth}{\strut#1\strut}}
|
|
\newcommand{\CSLRightInline}[1]{\parbox[t]{\linewidth - \csllabelwidth}{\strut#1\strut}}
|
|
\newcommand{\CSLIndent}[1]{\hspace{\cslhangindent}#1}
|
|
\setlength{\emergencystretch}{3em} % prevent overfull lines
|
|
\providecommand{\tightlist}{%
|
|
\setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}
|
|
\usepackage{etoolbox}
|
|
\usepackage[most]{tcolorbox}
|
|
\usepackage{graphicx}
|
|
\usepackage{xparse}
|
|
\usepackage{titlesec}
|
|
\tcbuselibrary{breakable}
|
|
|
|
% --- Disable floating figures globally ---
|
|
\usepackage{float}
|
|
\let\origfigure\figure
|
|
\let\endorigfigure\endfigure
|
|
\renewenvironment{figure}[1][H]{\origfigure[H]}{\endorigfigure}
|
|
|
|
% --- Colors ---
|
|
\usepackage{xcolor}
|
|
\definecolor{speculativeback}{RGB}{247,232,255} % #f7e8ff
|
|
\definecolor{speculativeframe}{RGB}{139,43,226} % #8b2be2
|
|
\definecolor{lightgrayback}{RGB}{245,245,245}
|
|
\definecolor{lightgrayframe}{RGB}{180,180,180}
|
|
|
|
% --- Left-align all Pandoc tables ---
|
|
\usepackage{longtable}
|
|
\usepackage{etoolbox}
|
|
\makeatletter
|
|
\patchcmd\longtable{\par}{\par\raggedright}{}{}
|
|
\setlength{\LTleft}{0pt}
|
|
\setlength{\LTright}{0pt}
|
|
\makeatother
|
|
|
|
% Enable index generation
|
|
\usepackage{makeidx}
|
|
\makeindex
|
|
|
|
|
|
% Helper to show a blank title if empty
|
|
\newcommand{\blanktitle}{\mbox{}}
|
|
|
|
|
|
% =========================================================
|
|
% Chapter Formatting (Suppress "Chapter 1")
|
|
% =========================================================
|
|
|
|
\titleformat{\chapter}[display]
|
|
{\normalfont\huge\bfseries} % formatting of title text
|
|
{} % <-- empty label removes "Chapter 1"
|
|
{0pt} % space between label and title
|
|
{\Huge} % formatting of title itself
|
|
|
|
\titlespacing*{\chapter}
|
|
{0pt} % left margin
|
|
{0pt} % space before title
|
|
{20pt} % space after title
|
|
|
|
% =========================================================
|
|
% Concept Boxes
|
|
% =========================================================
|
|
\newtcolorbox{infobox}[1][Information]{%
|
|
title=\ifstrempty{#1}{\blanktitle}{#1},
|
|
colback=blue!3!white,
|
|
colframe=blue!50!black,
|
|
colbacktitle=blue!10!white,
|
|
fonttitle=\bfseries,
|
|
coltitle=black,
|
|
enhanced, sharp corners, breakable,
|
|
after=\par\vspace{6pt}
|
|
}
|
|
|
|
\newtcolorbox{proposedbox}[1][Proposed Concept]{%
|
|
title=\ifstrempty{#1}{\blanktitle}{#1},
|
|
colback=blue!5!white,
|
|
colframe=blue!75!black,
|
|
colbacktitle=blue!15!white,
|
|
fonttitle=\bfseries,
|
|
coltitle=black,
|
|
enhanced, sharp corners, breakable,
|
|
after=\par\vspace{6pt}
|
|
}
|
|
|
|
\newtcolorbox{establishedbox}[1][Established Concept]{%
|
|
title=\ifstrempty{#1}{\blanktitle}{#1},
|
|
colback=green!5!white,
|
|
colframe=green!75!black,
|
|
colbacktitle=green!15!white,
|
|
fonttitle=\bfseries,
|
|
coltitle=black,
|
|
enhanced, sharp corners, breakable,
|
|
after=\par\vspace{6pt}
|
|
}
|
|
|
|
\newtcolorbox{speculativebox}[1][Speculative Concept]{%
|
|
title=\ifstrempty{#1}{\blanktitle}{#1},
|
|
colback=speculativeback,
|
|
colframe=speculativeframe,
|
|
colbacktitle=speculativeback!80!white, % lighter variant for title bar
|
|
fonttitle=\bfseries,
|
|
coltitle=black,
|
|
enhanced, sharp corners, breakable,
|
|
after=\par\vspace{6pt}
|
|
}
|
|
|
|
|
|
\newtcolorbox{cautionbox}[1][Caution]{%
|
|
title=\ifstrempty{#1}{\blanktitle}{#1},
|
|
colback=orange!5!white,
|
|
colframe=orange!75!black,
|
|
colbacktitle=orange!15!white,
|
|
fonttitle=\bfseries,
|
|
coltitle=black,
|
|
enhanced, sharp corners, breakable,
|
|
after=\par\vspace{6pt}
|
|
}
|
|
|
|
\newtcolorbox{warningbox}[1][Warning]{%
|
|
title=\ifstrempty{#1}{\blanktitle}{#1},
|
|
colback=orange!5!white,
|
|
colframe=orange!75!black,
|
|
colbacktitle=orange!15!white,
|
|
fonttitle=\bfseries,
|
|
coltitle=black,
|
|
enhanced, sharp corners, breakable,
|
|
after=\par\vspace{6pt}
|
|
}
|
|
|
|
\newtcolorbox{dangerbox}[1][Danger]{%
|
|
title=\ifstrempty{#1}{\blanktitle}{#1},
|
|
colback=red!5!white,
|
|
colframe=red!75!black,
|
|
colbacktitle=red!15!white,
|
|
fonttitle=\bfseries,
|
|
coltitle=black,
|
|
enhanced, sharp corners, breakable,
|
|
after=\par\vspace{6pt}
|
|
}
|
|
|
|
|
|
% =========================================================
|
|
% Code / CLI Boxes
|
|
% =========================================================
|
|
|
|
\newtcolorbox{codebox}[1][Code]{%
|
|
title=\ifstrempty{#1}{\blanktitle}{#1},
|
|
colback=lightgrayback,
|
|
colframe=lightgrayframe,
|
|
colbacktitle=lightgrayback!90!white,
|
|
fonttitle=\bfseries,
|
|
coltitle=black,
|
|
enhanced, sharp corners, breakable,
|
|
after=\par\vspace{6pt}
|
|
}
|
|
|
|
\newtcolorbox{clibox}[1][Command Line]{%
|
|
title=\ifstrempty{#1}{\blanktitle}{#1},
|
|
colback=lightgrayback,
|
|
colframe=lightgrayframe,
|
|
colbacktitle=lightgrayback!90!white,
|
|
fonttitle=\bfseries,
|
|
coltitle=black,
|
|
enhanced, sharp corners, breakable,
|
|
after=\par\vspace{6pt}
|
|
}
|
|
|
|
\usepackage{xurl}
|
|
|
|
\usepackage{fancyhdr}
|
|
\setlength{\headheight}{15pt}
|
|
|
|
% --- Chapter-opening pages (plain style) ---
|
|
\fancypagestyle{plain}{%
|
|
\fancyhf{}%
|
|
\fancyhead[C]{\leftmark} % Chapter title
|
|
\cfoot{Basic Book Builder: A Pandoc build process for books, docs and articles.} % Book title
|
|
\rfoot{\thepage} % Page number
|
|
\renewcommand{\headrulewidth}{0pt}
|
|
\renewcommand{\footrulewidth}{0pt}
|
|
}
|
|
|
|
% --- Normal running pages ---
|
|
\pagestyle{fancy}
|
|
\fancyhf{}
|
|
|
|
% Header
|
|
\fancyhead[C]{\leftmark} % Chapter title (centered)
|
|
|
|
% Footer
|
|
\cfoot{Basic Book Builder: A Pandoc build process for books, docs and articles.} % Book title
|
|
\rfoot{\thepage} % Page number
|
|
|
|
% Line rules
|
|
\renewcommand{\headrulewidth}{0pt} % rule under header
|
|
\renewcommand{\footrulewidth}{0pt} % no rule above footer
|
|
\usepackage{bookmark}
|
|
\IfFileExists{xurl.sty}{\usepackage{xurl}}{} % add URL line breaks if available
|
|
\urlstyle{same}
|
|
\hypersetup{
|
|
colorlinks=true,
|
|
linkcolor={blue},
|
|
filecolor={Maroon},
|
|
citecolor={Blue},
|
|
urlcolor={Blue},
|
|
pdfcreator={LaTeX via pandoc}}
|
|
|
|
\author{}
|
|
\date{}
|
|
|
|
\begin{document}
|
|
\frontmatter
|
|
|
|
% -------------------------
|
|
% 1. Title Page
|
|
% -------------------------
|
|
\begin{titlepage}
|
|
\centering
|
|
|
|
\vspace*{2cm}
|
|
|
|
{\Huge\bfseries Basic Book Builder \par}
|
|
\vspace{0.4cm}
|
|
{\Large A Pandoc build process for books, docs and articles. \par}
|
|
|
|
\vspace{1.2cm}
|
|
\includegraphics[width=0.5\textwidth]{lib/img/UAF-ACEP.png}
|
|
|
|
\vfill
|
|
|
|
\end{titlepage}
|
|
|
|
% -------------------------
|
|
% 2. COPYRIGHT / META PAGE
|
|
% -------------------------
|
|
\newpage
|
|
\thispagestyle{empty}
|
|
|
|
{\Large\bfseries Basic Book Builder \par}
|
|
\vspace{0.2cm}
|
|
{\normalsize\textit{A Pandoc build process for books, docs and articles.}\par}
|
|
\vspace{0.4cm}
|
|
|
|
\renewcommand{\arraystretch}{1.3} % row spacing
|
|
\setlength{\tabcolsep}{8pt} % column padding
|
|
\begin{tabular}{@{}p{0.28\textwidth}p{0.65\textwidth}@{}}
|
|
\textbf{Author:} & John Haverlack \\
|
|
\textbf{Version:} & 1.2.3 \\
|
|
\textbf{Date:} & 2026-02-05 \\
|
|
\textbf{Affiliation:} & Alaska Center for Energy and Power \\
|
|
\textbf{Institution:} & University of Alaska Fairbanks \\
|
|
\textbf{ISBN:} & UNSPECIFIED \\
|
|
\textbf{DOI:} & UNSPECIFIED \\
|
|
\textbf{Maturity:} & BETA \\
|
|
\end{tabular}
|
|
|
|
\vspace{0.5cm}
|
|
|
|
\textbf{Copyright} © 2026 Alaska Center for Energy and Power
|
|
|
|
\vspace{0.5cm}
|
|
|
|
% ----- Licensing Section -----
|
|
\section*{Licensing}
|
|
|
|
\subsection*{Open Source Edition (PDF and HTML)}
|
|
Licensed under the Creative Commons Attribution-NoDerivatives 4.0 International License.
|
|
|
|
\begin{itemize}
|
|
\item License: \href{https://creativecommons.org/licenses/by-nd/4.0/}{CC BY-ND 4.0}
|
|
\end{itemize}
|
|
|
|
% \subsection*{Commercial Edition (ebook and print)}
|
|
% All Rights Reserved. No part of the EPUB or printed editions may be reproduced or redistributed without permission.
|
|
|
|
\vspace*{\fill}
|
|
|
|
% -------------------------
|
|
% 3. Cover Illustration Page
|
|
% -------------------------
|
|
% ----- Title Page Image Note -----
|
|
\newpage
|
|
\thispagestyle{empty}
|
|
|
|
% \vspace*{1.5cm}
|
|
|
|
% {\Large\bfseries Cover Illustration\par}
|
|
|
|
% \begin{center}
|
|
% \includegraphics[width=0.33\textwidth]{lib/img/UAF-ACEP.png}
|
|
|
|
% \vspace{0.6cm}
|
|
|
|
|
|
% \vspace{0.8cm}
|
|
|
|
% {\small
|
|
% \textit{“Cover illustration by****”}
|
|
% \end{center}
|
|
|
|
|
|
% -------------------------
|
|
% Reset numbering
|
|
% -------------------------
|
|
\clearpage
|
|
\pagenumbering{roman}
|
|
|
|
% -------------------------
|
|
% Insert dedication
|
|
% -------------------------
|
|
|
|
% \begin{titlepage}
|
|
% \centering
|
|
% \vspace*{\fill}
|
|
|
|
% \textit{This book is dedicated to ****.}
|
|
|
|
% \vspace*{\fill}
|
|
% \end{titlepage}
|
|
|
|
% (Pandoc will insert the TOC next, using roman numerals)
|
|
|
|
\renewcommand*\contentsname{Contents}
|
|
{
|
|
\setcounter{tocdepth}{3}
|
|
\tableofcontents
|
|
}
|
|
\mainmatter
|
|
\chapter{Introduction}\label{introduction}
|
|
|
|
This is a \textbf{basic book builder} template is based on a
|
|
Pandoc(\citeproc{ref-PandocIndex}{\emph{Pandoc - Index},
|
|
n.d.})\index{Pandoc} + Makefile build process in conjunction Obsidian to
|
|
edit content and Zotero to manage citation, to generate multiple format
|
|
of the document including:
|
|
|
|
\begin{itemize}
|
|
\tightlist
|
|
\item
|
|
PDF
|
|
\item
|
|
HTML
|
|
\item
|
|
\emph{LaTeX}
|
|
\item
|
|
Markdown
|
|
\item
|
|
ODT
|
|
\item
|
|
DOCX
|
|
\item
|
|
Epub
|
|
\end{itemize}
|
|
|
|
\subsection{Workflow}\label{workflow}
|
|
|
|
\begin{enumerate}
|
|
\def\labelenumi{\arabic{enumi}.}
|
|
\tightlist
|
|
\item
|
|
Create a new project
|
|
\item
|
|
Initialize \texttt{metadata.yaml} with title, copyright, author, etc.
|
|
\item
|
|
Customize \texttt{input-files:} in \texttt{pandoc.yaml}
|
|
\item
|
|
Edit \texttt{chapters} Markdown ``conent'' files using Obidian
|
|
\item
|
|
Build your document
|
|
\end{enumerate}
|
|
|
|
This \textbf{basic book
|
|
builder}(\citeproc{ref-JehaverlackBasicbookbuilderPandoca}{\emph{Jehaverlack/Basic-Book-Builder},
|
|
n.d.}) template has been curated by John
|
|
Haverlack.(\citeproc{ref-JohnHaverlackACEP}{\emph{John {Haverlack}
|
|
\textbar{} {ACEP}}, n.d.})
|
|
|
|
\chapter{Getting Started}\label{getting-started}
|
|
|
|
\section{Clone the Basic Book
|
|
Builder}\label{clone-the-basic-book-builder}
|
|
|
|
\begin{clibox}[Clone the repository]
|
|
\begin{verbatim}
|
|
git clone https://github.com/jehaverlack/basic-book-builder.git
|
|
\end{verbatim}
|
|
|
|
\end{clibox}
|
|
|
|
\begin{clibox}[Navigate to the repo directory]
|
|
\begin{verbatim}
|
|
cd basic-book-builder
|
|
\end{verbatim}
|
|
|
|
\end{clibox}
|
|
|
|
\section{Setting Up Build
|
|
Environment}\label{setting-up-build-environment}
|
|
|
|
\begin{cautionbox}[~Debian Linux]
|
|
This script only support Debian based Linux system (e.g Debian, Ubuntu,
|
|
Zorin). And this script will install several ATP packages on your
|
|
system.
|
|
\end{cautionbox}
|
|
|
|
\begin{dangerbox}[Warning]
|
|
This script \textbf{has not} been widely tested across many platforms
|
|
\end{dangerbox}
|
|
|
|
To initialize your systems build environment run:
|
|
|
|
\begin{clibox}[Setup Build Environment]
|
|
\begin{verbatim}
|
|
./scripts/setup-linux-deb.sh
|
|
\end{verbatim}
|
|
|
|
\end{clibox}
|
|
|
|
\subsection{Non deb systems}\label{non-deb-systems}
|
|
|
|
For more information on setting up the build environment for your system
|
|
see: \textbf{TBD: NEEDS DOCUMENTED}.
|
|
|
|
\section{Testing}\label{testing}
|
|
|
|
Once you have set up your build environment, you test by building the
|
|
\textbf{basic book builder}.
|
|
|
|
\begin{clibox}[Testing Build Environment]
|
|
\begin{verbatim}
|
|
make all
|
|
\end{verbatim}
|
|
|
|
\end{clibox}
|
|
|
|
\section{Creating a New Project}\label{creating-a-new-project}
|
|
|
|
\begin{proposedbox}[Tip]
|
|
You do not want to edit your new project document in the
|
|
\texttt{basic-book-builder} directory. You will want to create a
|
|
\textbf{new project} for your document based on this template.
|
|
\end{proposedbox}
|
|
|
|
\begin{clibox}[Create a new project]
|
|
\begin{verbatim}
|
|
./scripts/new-project.sh <NEW_PROJECT_DIR>
|
|
\end{verbatim}
|
|
|
|
\end{clibox}
|
|
|
|
\begin{verbatim}
|
|
cd <NEW_PROJECT_DIR>
|
|
\end{verbatim}
|
|
|
|
Update your project configuration:
|
|
|
|
\begin{enumerate}
|
|
\def\labelenumi{\arabic{enumi}.}
|
|
\tightlist
|
|
\item
|
|
Edit: \texttt{metadata.yaml}, for title, author, etc
|
|
\item
|
|
Edit: \texttt{templates/pandoc.yaml}
|
|
\item
|
|
Open: \texttt{\textless{}NEW\_PROJECT\_DIR\textgreater{}} with
|
|
Obsidian, and edit \texttt{chapters} documents.
|
|
\item
|
|
Build: \texttt{make\ pdf}
|
|
\end{enumerate}
|
|
|
|
\begin{warningbox}[Warning]
|
|
\texttt{\textless{}NEW\_PROJECT\_DIR\textgreater{}} should be outside of
|
|
the \textbf{basic-book-builder} directory
|
|
\end{warningbox}
|
|
|
|
\section{Building}\label{building}
|
|
|
|
\subsection{PDF}\label{pdf}
|
|
|
|
\begin{verbatim}
|
|
make pdf
|
|
\end{verbatim}
|
|
|
|
\begin{quote}
|
|
NOTE: Building the PDF also builds the \textbf{LaTeX} version of the
|
|
book.
|
|
\end{quote}
|
|
|
|
\subsection{HTML}\label{html}
|
|
|
|
\begin{verbatim}
|
|
make html
|
|
\end{verbatim}
|
|
|
|
\subsection{DocX}\label{docx}
|
|
|
|
\begin{verbatim}
|
|
make docx
|
|
\end{verbatim}
|
|
|
|
\begin{quote}
|
|
NOTE: DocX is a work in progress. Frontmatter and formatting need work.
|
|
\end{quote}
|
|
|
|
\subsection{ODT}\label{odt}
|
|
|
|
\begin{verbatim}
|
|
make odt
|
|
\end{verbatim}
|
|
|
|
\begin{quote}
|
|
NOTE: ODT is a work in progress. Frontmatter and formatting need work.
|
|
\end{quote}
|
|
|
|
\subsection{Make All}\label{make-all}
|
|
|
|
To build all supported formats
|
|
|
|
\begin{verbatim}
|
|
make all
|
|
\end{verbatim}
|
|
|
|
\chapter{Features}\label{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.
|
|
|
|
\section{Metadata}\label{metadata}
|
|
|
|
Metadata for the project is managed in \texttt{metadata.yaml}. Edit this
|
|
file to make \textbf{global changes} to variables for your document.
|
|
Definitions in \texttt{metadata.yaml} will propagate to all format
|
|
builds.
|
|
|
|
\section{Front-matter}\label{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:
|
|
|
|
\begin{itemize}
|
|
\tightlist
|
|
\item
|
|
\texttt{templates/frontmatter.tex}
|
|
\item
|
|
\texttt{templates/frontmatter.html}
|
|
\item
|
|
\texttt{templates/frontmatter-md.html}
|
|
\end{itemize}
|
|
|
|
Unfortunately when you edit one, you need to edit the respective changes
|
|
to the other front-matter formats. \#\#\# Title Page
|
|
|
|
Edit the \textbf{Front-matter} files to modify the formatting of the
|
|
Title Page. You'll need to modify the HTML / LaTex code.
|
|
|
|
\subsection{Meta Data Page}\label{meta-data-page}
|
|
|
|
Edit the \textbf{Front-matter} files to modify the 2nd page Metadata
|
|
format and fields to display.
|
|
|
|
\subsection{Cover Illustration}\label{cover-illustration}
|
|
|
|
Edit the \textbf{Front-matter} files to optionally un-comment the Cover
|
|
Art Acknowledgement.
|
|
|
|
\begin{itemize}
|
|
\tightlist
|
|
\item
|
|
This is disabled by default
|
|
\end{itemize}
|
|
|
|
\subsection{Dedication}\label{dedication}
|
|
|
|
Edit the \textbf{Front-matter} files to modify un-comment the Book
|
|
Dedication.
|
|
|
|
\begin{itemize}
|
|
\tightlist
|
|
\item
|
|
This is disabled by default
|
|
\end{itemize}
|
|
|
|
\section{Table of Contents}\label{table-of-contents}
|
|
|
|
The table of contents is auto generated. But can be disabled in
|
|
\texttt{template\textbackslash{}pandoc.yaml} by setting: -
|
|
\texttt{toc:\ false}
|
|
|
|
\section{Chapters}\label{chapters}
|
|
|
|
Chapter Markdown source files are located in the \texttt{chapters}
|
|
directory. To edit which chapter files are included the document:
|
|
|
|
\begin{itemize}
|
|
\tightlist
|
|
\item
|
|
Edit the \texttt{input-file:} section of the
|
|
\texttt{template\textbackslash{}pandoc.yaml}
|
|
\end{itemize}
|
|
|
|
\section{Appendixes}\label{appendixes}
|
|
|
|
TBD
|
|
|
|
\section{Glossary}\label{glossary}
|
|
|
|
TBD
|
|
|
|
\section{Index}\label{index}
|
|
|
|
TBD
|
|
|
|
\subsection{Markdown Indexes}\label{markdown-indexes}
|
|
|
|
TBD
|
|
|
|
\section{Bibliography}\label{bibliography}
|
|
|
|
TBD
|
|
|
|
\subsection{Zotero Integration}\label{zotero-integration}
|
|
|
|
TBD
|
|
|
|
\subsection{Obsidian Citations}\label{obsidian-citations}
|
|
|
|
TBD
|
|
|
|
\section{Images}\label{images}
|
|
|
|
You can use basic Markdown Images
|
|
|
|
\begin{verbatim}
|
|
|
|
\end{verbatim}
|
|
|
|
\begin{figure}
|
|
\centering
|
|
\pandocbounded{\includegraphics[keepaspectratio,alt={ACEP}]{lib/img/ACEPLogo.png}}
|
|
\caption{ACEP}
|
|
\end{figure}
|
|
|
|
\section{\texorpdfstring{\emph{LaTeX}
|
|
Equations}{LaTeX Equations}}\label{latex-equations}
|
|
|
|
You can embed LaTeX equations directly in your Markdown pages.
|
|
|
|
\subsection{Left Justified / Inline}\label{left-justified-inline}
|
|
|
|
To left justify \emph{LaTex} surround the code inside single
|
|
\texttt{\$}:
|
|
|
|
\begin{codebox}[Left Justified Equation]
|
|
\begin{verbatim}
|
|
$x = \frac{1}{2}$
|
|
\end{verbatim}
|
|
|
|
\end{codebox}
|
|
|
|
\(x = \frac{1}{2}\)
|
|
|
|
\begin{codebox}[Inline]
|
|
\begin{verbatim}
|
|
Or inline, $x = \frac{1}{2}$, in a sentence.
|
|
\end{verbatim}
|
|
|
|
\end{codebox}
|
|
|
|
Or inline, \(x = \frac{1}{2}\), in a sentence.
|
|
|
|
\subsection{Centered}\label{centered}
|
|
|
|
To center justify \emph{LaTex} surround the code inside double
|
|
\texttt{\$\$}:
|
|
|
|
\begin{codebox}[Centered Equation]
|
|
\begin{verbatim}
|
|
$$x = \frac{1}{2}$$
|
|
\end{verbatim}
|
|
|
|
\end{codebox}
|
|
|
|
\[x = \frac{1}{2}\]
|
|
|
|
\section{Custom Markdown}\label{custom-markdown}
|
|
|
|
\subsection{Call-outs}\label{call-outs}
|
|
|
|
A few call-out box styles have been custom added to easily highlight
|
|
certain types of content.
|
|
|
|
\begin{codebox}[Markdown Example]
|
|
\begin{verbatim}
|
|
[!established] Green Call-out Title
|
|
A green box
|
|
\end{verbatim}
|
|
|
|
\end{codebox}
|
|
|
|
Will render:
|
|
|
|
\begin{establishedbox}[Green Call-out Title]
|
|
A green box
|
|
\end{establishedbox}
|
|
|
|
\begin{center}\rule{0.5\linewidth}{0.5pt}\end{center}
|
|
|
|
\begin{codebox}[Markdown Example]
|
|
\begin{verbatim}
|
|
[!proposed] Blue Call-out Title
|
|
A blue box
|
|
\end{verbatim}
|
|
|
|
\end{codebox}
|
|
|
|
Will render:
|
|
|
|
\begin{proposedbox}[Blue Call-out Title]
|
|
A blue box
|
|
\end{proposedbox}
|
|
|
|
\begin{center}\rule{0.5\linewidth}{0.5pt}\end{center}
|
|
|
|
\begin{codebox}[Markdown Example]
|
|
\begin{verbatim}
|
|
[!speculative] Purple Call-out Title
|
|
A purple box
|
|
\end{verbatim}
|
|
|
|
\end{codebox}
|
|
|
|
Will render:
|
|
|
|
\begin{speculativebox}[Purple Call-out Title]
|
|
A purple box
|
|
\end{speculativebox}
|
|
|
|
\begin{center}\rule{0.5\linewidth}{0.5pt}\end{center}
|
|
|
|
\begin{codebox}[Markdown Example]
|
|
\begin{verbatim}
|
|
[!caution] Caution Note
|
|
Beware of this section. AKA a orange box.
|
|
\end{verbatim}
|
|
|
|
\end{codebox}
|
|
|
|
Will render:
|
|
|
|
\begin{cautionbox}[Caution Note]
|
|
Beware of this section. AKA a orange box.
|
|
\end{cautionbox}
|
|
|
|
\begin{center}\rule{0.5\linewidth}{0.5pt}\end{center}
|
|
|
|
\begin{codebox}[Markdown Example]
|
|
\begin{verbatim}
|
|
[!warning] Warning Note
|
|
Same as the Caution Box
|
|
\end{verbatim}
|
|
|
|
\end{codebox}
|
|
|
|
Will render:
|
|
|
|
\begin{warningbox}[Warning Note]
|
|
Same as the Caution Box
|
|
\end{warningbox}
|
|
|
|
\begin{center}\rule{0.5\linewidth}{0.5pt}\end{center}
|
|
|
|
\begin{codebox}[Markdown Example]
|
|
\begin{verbatim}
|
|
[!danger] Alert
|
|
A slightly stronger warning. AKA a red box.
|
|
\end{verbatim}
|
|
|
|
\end{codebox}
|
|
|
|
Will render:
|
|
|
|
\begin{dangerbox}[Alert]
|
|
A slightly stronger warning. AKA a red box.
|
|
\end{dangerbox}
|
|
|
|
\begin{center}\rule{0.5\linewidth}{0.5pt}\end{center}
|
|
|
|
\begin{codebox}[Markdown Example]
|
|
\begin{verbatim}
|
|
[!code] Code Block
|
|
'''
|
|
if [ true ]; do
|
|
echo "The Cow Jumps over the Moon"
|
|
fi
|
|
'''
|
|
\end{verbatim}
|
|
|
|
\end{codebox}
|
|
|
|
Will render:
|
|
|
|
\begin{codebox}[Code Block]
|
|
\begin{verbatim}
|
|
if [ true ]; do
|
|
echo "The Cow Jumps over the Moon"
|
|
fi
|
|
\end{verbatim}
|
|
|
|
\end{codebox}
|
|
|
|
\begin{center}\rule{0.5\linewidth}{0.5pt}\end{center}
|
|
|
|
\begin{codebox}[Markdown Example]
|
|
\begin{verbatim}
|
|
[!cli] Command line
|
|
A command line example
|
|
'''
|
|
$ ls
|
|
build chapters conf filters lib LICENSE.md Makefile
|
|
metadata.yaml >README.md scripts templates
|
|
'''
|
|
\end{verbatim}
|
|
|
|
\end{codebox}
|
|
|
|
Will render:
|
|
|
|
\begin{clibox}[Command line]
|
|
A command line example
|
|
|
|
\begin{verbatim}
|
|
$ ls
|
|
build chapters conf filters lib LICENSE.md Makefile
|
|
metadata.yaml README.md scripts templates
|
|
\end{verbatim}
|
|
|
|
\end{clibox}
|
|
|
|
\section{Advanced}\label{advanced}
|
|
|
|
\subsection{Changing Fonts}\label{changing-fonts}
|
|
|
|
It is possible to change fonts by editing
|
|
\texttt{templates/pandoc.yaml}, and
|
|
\texttt{templates\textbackslash{}styles.css}, but you will have to make
|
|
sure you have the proper font's installed on your system first.
|
|
|
|
\subsection{Adding Filters}\label{adding-filters}
|
|
|
|
Custom filters can be created. This is complicated and typically needs
|
|
done in 3 places for:
|
|
|
|
\begin{itemize}
|
|
\tightlist
|
|
\item
|
|
obsidian
|
|
\item
|
|
\emph{LaTeX}
|
|
\item
|
|
HTML
|
|
\end{itemize}
|
|
|
|
\chapter{Design}\label{design}
|
|
|
|
\section{Directory Structure}\label{directory-structure}
|
|
|
|
The \textbf{basic-book-builder} directory tree.
|
|
|
|
\begin{verbatim}
|
|
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
|
|
\end{verbatim}
|
|
|
|
\section{Configuration Files}\label{configuration-files}
|
|
|
|
The \textbf{basic-book-builder} configuration files, scripts, and build
|
|
files.
|
|
|
|
\begin{verbatim}
|
|
../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
|
|
\end{verbatim}
|
|
|
|
\begin{cautionbox}[About conf]
|
|
NEVER: edit file directly in \texttt{conf}. They will be overwritten by
|
|
the build process. \#\#\# Metadata
|
|
\end{cautionbox}
|
|
|
|
Update the \texttt{metadata.yaml} file to globally configure your
|
|
document title and other metadata. Edit this file to control your
|
|
document title, author, etc.
|
|
|
|
\subsection{Pandoc Main Config}\label{pandoc-main-config}
|
|
|
|
Update the \texttt{input-files:} section of
|
|
\texttt{templates/pandoc.yaml} to control what chapter source files are
|
|
in which order in your document.
|
|
|
|
\begin{verbatim}
|
|
# 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
|
|
\end{verbatim}
|
|
|
|
\section{Build Workflow}\label{build-workflow}
|
|
|
|
For a PDF Build:
|
|
|
|
\begin{verbatim}
|
|
make pdf
|
|
\end{verbatim}
|
|
|
|
will build dependencies on these file:
|
|
|
|
\begin{enumerate}
|
|
\def\labelenumi{\arabic{enumi}.}
|
|
\tightlist
|
|
\item
|
|
Makefile
|
|
\item
|
|
conf/pandoc.yaml
|
|
\item
|
|
conf/pdf.yaml
|
|
\item
|
|
lib/zotero.bib
|
|
\item
|
|
chapters/*.md
|
|
\end{enumerate}
|
|
|
|
NOTE: the \texttt{Makefile} will copy \texttt{templates/*.yaml} to
|
|
\texttt{conf/*.yaml}. \textbf{Never} edit \texttt{conf/*}directly.
|
|
|
|
\backmatter
|
|
|
|
\chapter*{Glossary}\label{glossary-1}
|
|
\addcontentsline{toc}{chapter}{Glossary}
|
|
|
|
{\def\LTcaptype{none} % do not increment counter
|
|
\begin{longtable}[]{@{}
|
|
>{\raggedright\arraybackslash}p{(\linewidth - 2\tabcolsep) * \real{0.1734}}
|
|
>{\raggedright\arraybackslash}p{(\linewidth - 2\tabcolsep) * \real{0.8266}}@{}}
|
|
\toprule\noalign{}
|
|
\begin{minipage}[b]{\linewidth}\raggedright
|
|
Term
|
|
\end{minipage} & \begin{minipage}[b]{\linewidth}\raggedright
|
|
Description
|
|
\end{minipage} \\
|
|
\midrule\noalign{}
|
|
\endhead
|
|
\bottomrule\noalign{}
|
|
\endlastfoot
|
|
\textbf{AST (Abstract Syntax Tree)} & Pandoc's internal structured
|
|
representation of a document. Lua filters operate on the AST before
|
|
rendering to a target format. \\
|
|
\textbf{Bibliography} & A \texttt{.bib} file (e.g., Zotero export) used
|
|
by Pandoc with \texttt{citeproc} to generate formatted citations and
|
|
reference lists. \\
|
|
\textbf{Callout} & A styled block (e.g., \texttt{{[}!warning{]}})
|
|
transformed by Lua filters into format-specific output such as LaTeX
|
|
environments or HTML \texttt{\textless{}div\textgreater{}} elements. \\
|
|
\textbf{Defaults File (YAML)} & A Pandoc configuration file defining
|
|
output format, filters, metadata, and rendering options (e.g.,
|
|
\texttt{pdf.yaml}, \texttt{html.yaml}). \\
|
|
\textbf{DOCX} & Microsoft Word document format generated by Pandoc;
|
|
styling is controlled via a \texttt{reference.docx} file. \\
|
|
\textbf{Filter (Lua)} & A script that modifies Pandoc's AST before
|
|
rendering. Used in this workflow for callouts and other structural
|
|
transformations. \\
|
|
\textbf{Frontmatter} & Format-specific content inserted before the main
|
|
body (e.g., \texttt{frontmatter.tex}, \texttt{frontmatter.html},
|
|
\texttt{frontmatter-docx.md}). \\
|
|
\textbf{HTML} & Web output format generated by Pandoc, typically styled
|
|
via CSS and supporting interactive features. \\
|
|
\textbf{LaTeX} & Typesetting system used for high-quality PDF generation
|
|
via XeLaTeX in this workflow. \\
|
|
\textbf{Lua Filter} & A lightweight scripting extension used by Pandoc
|
|
to customize document transformations programmatically. \\
|
|
\textbf{Makefile} & Automation script orchestrating the build pipeline
|
|
for PDF, HTML, DOCX, ODT, and Markdown outputs. \\
|
|
\textbf{Markdown} & Plain-text markup language serving as the source
|
|
format for all outputs in the workflow. \\
|
|
\textbf{Metadata} & Key--value pairs (e.g., \texttt{metadata.yaml})
|
|
defining title, author, license, version, and other document
|
|
variables. \\
|
|
\textbf{ODT} & OpenDocument Text format used by LibreOffice; similar to
|
|
DOCX but open-standard. \\
|
|
\textbf{Pandoc} & Universal document converter used to transform
|
|
Markdown into PDF, HTML, DOCX, ODT, EPUB, and more. \\
|
|
\textbf{PDF} & Portable Document Format output produced via Pandoc +
|
|
XeLaTeX. \\
|
|
\textbf{Reference Document} & A DOCX or ODT file defining styles (fonts,
|
|
headings, spacing) used when generating Word/LibreOffice outputs. \\
|
|
\textbf{Resource Path} & Directories Pandoc searches for images,
|
|
diagrams, and other assets during rendering. \\
|
|
\textbf{Template} & A format-specific layout file (e.g., LaTeX template)
|
|
used to control document structure beyond styling. \\
|
|
\textbf{TOC (Table of Contents)} & Automatically generated navigation
|
|
structure controlled by \texttt{toc} and \texttt{toc-depth} options. \\
|
|
\textbf{XeLaTeX} & LaTeX engine used to generate PDFs with modern font
|
|
support (via \texttt{fontspec}). \\
|
|
\textbf{Zotero} & Reference manager used to generate \texttt{.bib} files
|
|
for citation processing with Pandoc. \\
|
|
\end{longtable}
|
|
}
|
|
|
|
\clearpage
|
|
\thispagestyle{plain}
|
|
\markboth{Index}{Index}
|
|
|
|
\let\oldclearpage\clearpage
|
|
\let\oldcleardoublepage\cleardoublepage
|
|
\renewcommand{\clearpage}{}
|
|
\renewcommand{\cleardoublepage}{}
|
|
|
|
\chapter*{Index}
|
|
\addcontentsline{toc}{chapter}{Index}
|
|
|
|
\printindex
|
|
|
|
\renewcommand{\clearpage}{\oldclearpage}
|
|
\renewcommand{\cleardoublepage}{\oldcleardoublepage}
|
|
|
|
\clearpage
|
|
\thispagestyle{plain}
|
|
\markboth{Bibliography}{Bibliography}
|
|
|
|
\chapter*{Bibliography}\label{bibliography-1}
|
|
\addcontentsline{toc}{chapter}{Bibliography}
|
|
|
|
\protect\phantomsection\label{refs}
|
|
\begin{CSLReferences}{1}{1}
|
|
\bibitem[\citeproctext]{ref-JehaverlackBasicbookbuilderPandoca}
|
|
\emph{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.
|
|
|
|
\bibitem[\citeproctext]{ref-JohnHaverlackACEP}
|
|
\emph{John {Haverlack} \textbar{} {ACEP}}. n.d.
|
|
Https://www.uaf.edu/acep/about/our-team/john-haverlack.php.
|
|
|
|
\bibitem[\citeproctext]{ref-PandocIndex}
|
|
\emph{Pandoc - Index}. n.d. Https://pandoc.org/.
|
|
|
|
\end{CSLReferences}
|
|
|
|
\backmatter
|
|
\end{document}
|