Cleanup readme
This commit is contained in:
parent
a2d7a9c03d
commit
8a169ce6d4
367
README.md
367
README.md
|
|
@ -1,366 +1,3 @@
|
||||||
# Pandoc book template
|
# Pyrotechnics Revived eBook
|
||||||
|
|
||||||
[](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: <Your table description>` 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
|
|
||||||
`{#<type>:<id>}` for definitions and `@<type>: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
|
|
||||||
`<div style="page-break-before: always;"></div>` you may use a `sed` filter:
|
|
||||||
|
|
||||||
```
|
|
||||||
CONTENT_FILTERS = sed 's/@pagebreak/"<div style=\"page-break-before: always;\"><\/div>"/g'
|
|
||||||
```
|
|
||||||
|
|
||||||
To use multiple filters, you may include multiple pipes on the `CONTENT_FILTERS` variable:
|
|
||||||
|
|
||||||
```
|
|
||||||
CONTENT_FILTERS = \
|
|
||||||
sed 's/@pagebreak/"<div style=\"page-break-before: always;\"><\/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)
|
|
||||||
|
|
||||||
|
Pyrotechics information preservation project in eBook format
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue