https://github.com/wikiti/pandoc-book-template
A simple Pandoc template to build documents and ebooks.
https://github.com/wikiti/pandoc-book-template
ebook epub html markdown pandoc pdf template
Last synced: 6 months ago
JSON representation
A simple Pandoc template to build documents and ebooks.
- Host: GitHub
- URL: https://github.com/wikiti/pandoc-book-template
- Owner: wikiti
- License: mit
- Created: 2017-01-15T18:51:40.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2024-05-27T20:17:16.000Z (over 1 year ago)
- Last Synced: 2024-08-03T13:04:31.371Z (over 1 year ago)
- Topics: ebook, epub, html, markdown, pandoc, pdf, template
- Language: CSS
- Homepage:
- Size: 78.1 KB
- Stars: 385
- Watchers: 12
- Forks: 88
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Pandoc book template
[](https://circleci.com/gh/wikiti/pandoc-book-template)
[](https://github.com/wikiti/pandoc-book-template/blob/master/LICENSE.md)
## Description
This repository contains a simple template for building [Pandoc](http://pandoc.org/) documents;
Pandoc is a suite of tools to compile markdown files into readable files (PDF, EPUB, HTML...).
## Usage
### Installing
Please, check [this page](http://pandoc.org/installing.html) for more information. On ubuntu, it
can be installed as the *pandoc* package:
```sh
sudo apt-get install pandoc
```
This template uses [make](https://www.gnu.org/software/make/) to build the output files, so don't
forget to install it too:
```sh
sudo apt-get install make
```
To export to PDF files, make sure to install the following packages:
```sh
sudo apt-get install texlive-fonts-recommended texlive-xetex
```
### Folder structure
Here's a folder structure for a Pandoc book:
```
my-book/ # Root directory.
|- build/ # Folder used to store builded (output) files.
|- chapters/ # Markdowns files; one for each chapter.
|- images/ # Images folder.
| |- cover.png # Cover page for epub.
|- metadata.yml # Metadata content (title, author...).
|- Makefile # Makefile used for building our books.
```
### Setup generic data
Edit the *metadata.yml* file to set configuration data (note that it must start and end with `---`):
```yml
---
title: My book title
author: Daniel Herzog
rights: MIT License
lang: en-US
tags: [pandoc, book, my-book, etc]
abstract: |
Your summary.
mainfont: DejaVu Sans
# Filter preferences:
# - pandoc-crossref
linkReferences: true
---
```
You can find the list of all available keys on
[this page](http://pandoc.org/MANUAL.html#extension-yaml_metadata_block).
### Creating chapters
Creating a new chapter is as simple as creating a new markdown file in the *chapters/* folder;
you'll end up with something like this:
```
chapters/01-introduction.md
chapters/02-installation.md
chapters/03-usage.md
chapters/04-references.md
```
Pandoc and Make will join them automatically ordered by name; that's why the numeric prefixes are
being used.
All you need to specify for each chapter at least one title:
```md
# Introduction
This is the first paragraph of the introduction chapter.
## First
This is the first subsection.
## Second
This is the second subsection.
```
Each title (*#*) will represent a chapter, while each subtitle (*##*) will represent a chapter's
section. You can use as many levels of sections as markdown supports.
#### Manual control over page ordering
You may prefer to have manual control over page ordering instead of using numeric prefixes.
To do so, replace `CHAPTERS = chapters/*.md` in the Makefile with your own order. For example:
```
CHAPTERS += $(addprefix ./chapters/,\
01-introduction.md\
02-installation.md\
03-usage.md\
04-references.md\
)
```
#### Links between chapters
Anchor links can be used to link chapters within the book:
```md
// chapters/01-introduction.md
# Introduction
For more information, check the [Usage] chapter.
// chapters/02-installation.md
# Usage
...
```
If you want to rename the reference, use this syntax:
```md
For more information, check [this](#usage) chapter.
```
Anchor names should be downcased, and spaces, colons, semicolons... should be replaced with hyphens.
Instead of `Chapter title: A new era`, you have: `#chapter-title-a-new-era`.
#### Links between sections
It's the same as anchor links:
```md
# Introduction
## First
For more information, check the [Second] section.
## Second
...
```
Or, with al alternative name:
```md
For more information, check [this](#second) section.
```
### Inserting objects
Text. That's cool. What about images and tables?
#### Insert an image
Use Markdown syntax to insert an image with a caption:
```md
```
Pandoc will automatically convert the image into a figure, using the title (the text between the
brackets) as a caption.
If you want to resize the image, you may use this syntax, available since Pandoc 1.16:
```md
{ width=50% height=50% }
```
#### Insert a table
Use markdown table, and use the `Table: ` syntax to add a caption:
```md
| Index | Name |
| ----- | ---- |
| 0 | AAA |
| 1 | BBB |
| ... | ... |
Table: This is an example table.
```
#### Insert an equation
Wrap a LaTeX math equation between `$` delimiters for inline (tiny) formulas:
```md
This, $\mu = \sum_{i=0}^{N} \frac{x_i}{N}$, the mean equation, ...
```
Pandoc will transform them automatically into images using online services.
If you want to center the equation instead of inlining it, use double `$$` delimiters:
```md
$$\mu = \sum_{i=0}^{N} \frac{x_i}{N}$$
```
[Here](https://www.codecogs.com/latex/eqneditor.php)'s an online equation editor.
#### Cross references
Originally, this template used LaTeX labels for auto numbering on images, tables, equations or
sections, like this:
```md
Please, admire the gloriousnes of Figure \ref{seagull_image}.
```
**However, these references only works when exporting to a LaTeX-based format (i.e. PDF, LaTeX).**
In case you need cross references support on other formats, this template now support cross
references using [Pandoc filters](https://pandoc.org/filters.html). If you want to use them, use a
valid plugin and with its own syntax.
Using [pandoc-crossref](https://github.com/lierdakil/pandoc-crossref) is highly recommended, but
there are other alternatives which use a similar syntax, like
[pandoc-xnos](https://github.com/tomduck/pandoc-xnos).
First, enable the filter on the *Makefile* by updating the `FILTER_ARGS` variable with your new
filter(s):
```make
FILTER_ARGS = --filter pandoc-crossref
```
Then, you may use the filter cross references. For example, *pandoc-crossref* uses
`{#:}` for definitions and `@:id` for referencing. Some examples:
```md
List of references:
- Check @fig:seagull.
- Check @tbl:table.
- Check @eq:equation.
List of elements to reference:
{#fig:seagull}
$$ y = mx + b $$ {#eq:equation}
| Index | Name |
| ----- | ---- |
| 0 | AAA |
| 1 | BBB |
| ... | ... |
Table: This is an example table. {#tbl:table}
```
Check the desired filter settings and usage for more information
([pandoc-crossref usage](http://lierdakil.github.io/pandoc-crossref/)).
#### Content filters
If you need to modify the MD content before passing it to pandoc, you may use `CONTENT_FILTERS`. By
setting this makefile variable, it will be passed to the markdown content before passing it to
pandoc. For example, to replace all occurrences of `@pagebreak` with
`
` you may use a `sed` filter:
```
CONTENT_FILTERS = sed 's/@pagebreak/"
<\/div>"/g'
```
To use multiple filters, you may include multiple pipes on the `CONTENT_FILTERS` variable:
```
CONTENT_FILTERS = \
sed 's/@pagebreak/"
<\/div>"/g' | \
sed 's/@image/[Cool image](\/images\/image.png)/g'
```
### Output
This template uses *Makefile* to automatize the building process. Instead of using the *pandoc cli
util*, we're going to use some *make* commands.
#### Export to PDF
Please note that PDF file generation requires some extra dependencies (~ 800 MB):
```sh
sudo apt-get install texlive-xetex ttf-dejavu
```
After installing the dependencies, use this command:
```sh
make pdf
```
The generated file will be placed in *build/pdf*.
#### Export to EPUB
Use this command:
```sh
make epub
```
The generated file will be placed in *build/epub*.
#### Export to HTML
Use this command:
```sh
make html
```
The generated file(s) will be placed in *build/html*.
#### Export to DOCX
Use this command:
```sh
make docx
```
The generated file(s) will be placed in *build/docx*.
#### Extra configuration
If you want to configure the output, you'll probably have to look the
[Pandoc Manual](http://pandoc.org/MANUAL.html) for further information about pdf (LaTeX) generation,
custom styles, etc, and modify the Makefile file accordingly.
#### Templates
Output files are generated using [pandoc templates](https://pandoc.org/MANUAL.html#templates). All
templates are located under the `templates/` folder, and may be modified as you will. Some basic
format templates are already included on this repository, ion case you need something to start
with.
## References
- [Pandoc](http://pandoc.org/)
- [Pandoc Manual](http://pandoc.org/MANUAL.html)
- [Wikipedia: Markdown](http://wikipedia.org/wiki/Markdown)