text:
Главная Introducing Markdown and Pandoc: Using Markup Language and Document Converter

# Introducing Markdown and Pandoc: Using Markup Language and Document Converter

Discover how to write manuscripts in Markdown and translate them with Pandoc into different output formats. You’ll use Markdown to annotate text formatting information with a strong focus on semantic information: you can annotate your text with information about where chapters and sections start, but not how chapter and heading captions should be formatted. As a result, you’ll decouple the structure of a text from how it is visualized and make it easier for you to produce different kinds of output. The same text can easily be formatted as HTML, PDF, or Word documents, with various visual styles, by tools that understand the markup annotations.

Finally, you’ll learn to use Pandoc, a tool for translating between different markup languages, such as LaTeX, HTML, and Markdown. This book will not describe all the functionality that Pandoc provides, but will teach you how to translate Markdown documents, how to customize your documents using templates, and how to extend Pandoc’s functionality using filters. If that is something you are interested in, Introducing Markdown and Pandoc will get you started.

With this set of skills you’ll be able to write more efficiently without worrying about needless formatting and other distractions.

What You Will Learn
• Why and how to use Markdown and Pandoc
• Write Markdown
• Use extensions available in Pandoc and Markdown
• Write math and code blocks
• Use templates and produce documents

Who This Book Is For
Programmers and problem solvers looking for technical documentation solutions.
Год:
2019
Издание:
1
Издательство:
Apress
Язык:
english
Страниц:
139 / 141
ISBN 10:
1484251482
ISBN 13:
978-1484251485
File:
PDF, 1.40 MB

## Most frequently terms

You can write a book review and share your experiences. Other readers will always be interested in your opinion of the books you've read. Whether you've loved the book or not, if you give your honest and detailed thoughts then people will find new books that are right for them.
1

Год:
1988
Язык:
english
File:
PDF, 19.18 MB
2

### Celtic Women: Women in Celtic Society and Literature

Год:
1996
Язык:
english
File:
PDF, 12.93 MB
Introducing
Markdown
and Pandoc
Using Markup Language and
Document Converter
—
Thomas Mailund

Introducing
Markdown and
Pandoc
Using Markup Language and
Document Converter

Thomas Mailund

Introducing Markdown and Pandoc: Using Markup Language and
Document Converter
Thomas Mailund
Aarhus N, Denmark
ISBN-13 (pbk): 978-1-4842-5148-5     ISBN-13 (electronic): 978-1-4842-5149-2
https://doi.org/10.1007/978-1-4842-5149-2

This work is subject to copyright. All rights are reserved by the Publisher, whether the whole or
part of the material is concerned, specifically the rights of translation, reprinting, reuse of
illustrations, recitation, broadcasting, reproduction on microfilms or in any other physical way,
and transmission or information storage and retrieval, electronic adaptation, computer software,
or by similar or dissimilar methodology now known or hereafter developed.
Trademarked names, logos, and images may appear in this book. Rather than use a trademark
symbol with every occurrence of a trademarked name, logo, or image we use the names, logos,
and images only in an editorial fashion and to the benefit of the trademark owner, with no
intention of infringement of the trademark.
The use in this publication of trade names, trademarks, service marks, and similar terms, even if
they are not identified as such, is not to be taken as an expression of opinion as to whether or not
they are subject to proprietary rights.
While the advice and information in this book are believed to be true and accurate at the date of
publication, neither the authors nor the editors nor the publisher can accept any legal
responsibility for any errors or omissions that may be made. The publisher makes no warranty,
express or implied, with respect to the material contained herein.
Managing Director, Apress Media LLC: Welmoed Spahr
Acquisitions Editor: Steve Anglin
Development Editor: Matthew Moodie
Coordinating Editor: Mark Powers
Cover designed by eStudioCalamar
Cover image designed by Freepik (; www.freepik.com)
Distributed to the book trade worldwide by Springer Science+Business Media New York,
233 Spring Street, 6th Floor, New York, NY 10013. Phone 1-800-SPRINGER, fax (201) 348-4505,
e-mail orders-ny@springer-sbm.com, or visit www.springeronline.com. Apress Media, LLC is a
California LLC and the sole member (owner) is Springer Science + Business Media Finance Inc
(SSBM Finance Inc). SSBM Finance Inc is a Delaware corporation.
For information on translations, please e-mail editorial@apress.com; for reprint, paperback, or
Apress titles may be purchased in bulk for academic, corporate, or promotional use. eBook
and eBook Bulk Sales web page at http://www.apress.com/bulk-sales.
Any source code or other supplementary material referenced by the author in this book is available
to readers on GitHub via the book’s product page, located at www.apress.com/9781484251485.
For more detailed information, please visit http://www.apress.com/source-code.
Printed on acid-free paper

Chapter 1: The Beginner’s Guide to Markdown and Pandoc�����������������1
Chapter 2: Why Use Markdown and Pandoc�����������������������������������������5
Separating Semantics from Formatting����������������������������������������������������������������6
Preprocessing Documents������������������������������������������������������������������������������������8
Why Markdown?���������������������������������������������������������������������������������������������������9
Why Pandoc?������������������������������������������������������������������������������������������������������11

Chapter 3: Writing Markdown������������������������������������������������������������13
Sections��������������������������������������������������������������������������������������������������������������13
Emphasis������������������������������������������������������������������������������������������������������������14
Lists��������������������������������������������������������������������������������������������������������������������15
Block Quotes�������������������������������������������������������������������������������������������������������17
Verbatim Text������������������������������������������������������������������������������������������������������18
Images����������������������������������������������������������������������������������������������������������������20
Exercises�������������������������������������������������������������������������������������������������������������20
Sections���������������������������������������������������������������������������������������������������������21
Emphasis�������������������������������������������������������������������������������������������������������21
Lists���������������������������������������������������������������������������������������������������������������21

iii

Block Quotes�������������������������������������������������������������������������������������������������21
Images�����������������������������������������������������������������������������������������������������������22

Chapter 4: Pandoc Markdown Extensions������������������������������������������23
Lists��������������������������������������������������������������������������������������������������������������������23
Tables������������������������������������������������������������������������������������������������������������������27
Smart Punctuation����������������������������������������������������������������������������������������������32
Footnotes������������������������������������������������������������������������������������������������������������33
Exercises�������������������������������������������������������������������������������������������������������������34
Lists���������������������������������������������������������������������������������������������������������������34
Tables������������������������������������������������������������������������������������������������������������34
Footnotes�������������������������������������������������������������������������������������������������������34

Chapter 5: Translating Documents�����������������������������������������������������35
Formatting a Markdown Document with Pandoc������������������������������������������������35
Frequently Useful Options�����������������������������������������������������������������������������������40
Sections and Chapters����������������������������������������������������������������������������������40
Image Extensions������������������������������������������������������������������������������������������41
Ebook Covers�������������������������������������������������������������������������������������������������42
Using Makefiles��������������������������������������������������������������������������������������������������42

Chapter 6: Math and Computer Programming Languages�����������������47
Writing Math�������������������������������������������������������������������������������������������������������47
Writing Code Blocks��������������������������������������������������������������������������������������������50
Code Block Options���������������������������������������������������������������������������������������������52
Syntax Highlighting Styles����������������������������������������������������������������������������������54
Exercises�������������������������������������������������������������������������������������������������������������55
iv

Code blocks���������������������������������������������������������������������������������������������������55
Code Block Options���������������������������������������������������������������������������������������55
Syntax Highlighting���������������������������������������������������������������������������������������55

Chapter 7: Cross-referencing�������������������������������������������������������������57
Referencing Sections������������������������������������������������������������������������������������������58
Reference Prefixes����������������������������������������������������������������������������������������������61
Referencing Figures, Tables, and Equations�������������������������������������������������������63
Bibliographies�����������������������������������������������������������������������������������������������������64
Exercises�������������������������������������������������������������������������������������������������������������66
Reference Sections���������������������������������������������������������������������������������������66
Figures, Tables, and Equations����������������������������������������������������������������������66
Bibliographies������������������������������������������������������������������������������������������������66

Chapter 9: Using Templates����������������������������������������������������������������73
Template Examples���������������������������������������������������������������������������������������78
Exercises�������������������������������������������������������������������������������������������������������������89

Chapter 10: Preprocessing�����������������������������������������������������������������91
Examples������������������������������������������������������������������������������������������������������������92
Including Files�����������������������������������������������������������������������������������������������92
Conditional Inclusion�������������������������������������������������������������������������������������94
Running Code������������������������������������������������������������������������������������������������96
Exercises�������������������������������������������������������������������������������������������������������������98

v

Chapter 11: Filters������������������������������������������������������������������������������99
Exploring Panflute���������������������������������������������������������������������������������������������104
Conditional Inclusion of Exercise Solutions������������������������������������������������������106
Conditional Inclusions Based on Format�����������������������������������������������������������112
Evaluating Code������������������������������������������������������������������������������������������������115
Numbering Exercises����������������������������������������������������������������������������������������119
Exercises�����������������������������������������������������������������������������������������������������������130
Conditional Inclusion�����������������������������������������������������������������������������������130
Conditional on Output����������������������������������������������������������������������������������130
Evaluating Code�������������������������������������������������������������������������������������������131
Numbering Exercises����������������������������������������������������������������������������������131

Chapter 12: Conclusions�������������������������������������������������������������������133
Index�������������������������������������������������������������������������������������������������135

vi

Thomas Mailund is an associate professor in bioinformatics at Aarhus
University, Denmark. He has a background in math and computer science.
For the past decade, his main focus has been on genetics and evolutionary
studies, particularly comparative genomics, speciation, and gene flow
between emerging species. He has published R Data Science Quick
Reference, The Joys of Hashing, Domain-Specific Languages in R, Beginning
Data Science in R, Functional Programming in R, and Metaprogramming
in R, all from Apress, as well as other books.

vii

Germán González-Morris is a polyglot software architect/engineer with
20+ years in the field, with knowledge in Java(EE), Spring, Haskell, C,
Python, and Javascript, among others. He works with web distributed
applications. Germán loves math puzzles (including reading Knuth) and
swimming. He has tech-reviewed several books, including an application
container book (Weblogic), as well as titles covering various programming
languages (Haskell, Typescript, WebAssembly, Math for coders, and
regexp). You can find more details at his blog site (https://devwebcl.

ix

CHAPTER 1

The Beginner’s
Guide to Markdown
and Pandoc
Markdown is a markup language. The name is a pun, but where the humor
might be atrocious, the language is not. The Markdown language lets
you write plain text documents with a few lightweight annotations that
specify how you want the document formatted. Such annotations are the
defining characteristics of a markup language. Markup languages separate
the semantic or content part of a document from the formatting of said
document. The content of a document is the text, what should be headers,
what should be emphasized, and so on. The formatting specifies the font
and font size, whether headers should be numbered, and so on.
Markup languages have a stronger focus on semantic information
than direct formatting as you would do with WYSIWYG (what you see is
what you get) formatting. With markup languages, you might annotate
not how chapter and heading captions should be formatted. Decoupling
the structure of a text from how it is visualized makes it easier for you to
produce different kinds of output. The same text can easily be transformed
into HTML, PDF, or Word documents by tools that understand the
markup annotations. And because writing the text and formatting it are
T. Mailund, Introducing Markdown and Pandoc,
https://doi.org/10.1007/978-1-4842-5149-2_1

1

Chapter 1

The Beginner’s Guide to Markdown and Pandoc

separate steps, you can apply one or more text documents to the same
transformation program to get a consistent look for related documents,
or you can transform the same document into multiple output formats
so the same document can be put on a web page or in a printed book, for
example. Most WYSIWYG editors can export to different formats, but they
usually do not let you output to the same document type with different
formatting, for example, output PDF files in A4, 6˝ x 9˝, and 7˝ x 10˝ with
point size 11 in the first two and 12 in the last. With a Markup language,
this is relatively easy.
Among markup languages, Markdown is one of, if not the, simplest.
The annotations you add to a text are minimal, and most likely you will
already have seen most of them if you occasionally use plain text files.
For example, where you would use italic or boldface in Word, you would
write *italic* and **boldface** in Markdown, and most likely you have
seen this notation before. In my misspelled youth, I frequently used
TeX/LaTeX and HTM-L/SGML/XML. I know people who cannot
concentrate on the text body if it is full of markup information. With
Markdown, the markup annotation is almost invisible, and they have no
problem working with that. With Markdown you can generate documents
in other markup languages, so you do not need to know them. If you want
the full power to format your documents the way you want them, then
I still recommend that you learn the other languages. You can use that
knowledge to create templates (see Chapter 9), and then you only need
to use, for example, LaTeX or HTML when writing the templates. You can
then still keep your document in Markdown. One exception, where you
still want to use LaTeX, is if you need to write math in your document.
Then you need to write it in LaTeX; see Chapter 6.
You need a program for translating Markdown into other file
formats. The tool I will use in this book is Pandoc. Pandoc supports
basic Markdown and several different extensions. It also lets you define
templates and stylesheets to customize the transformed files. Pandoc can

2

Chapter 1

The Beginner’s Guide to Markdown and Pandoc

do more than translate Markdown files into different output files. It can
translate from and to several different formats. I will only describe how
you translate from Markdown to other formats. If you have an existing text
in Word, for example, and you want to try out Markdown by editing that
document, then you should be able to generate a Markdown file from the
Word file, edit the Markdown format, and then translate the Markdown
document back to Word.

3

CHAPTER 2

Why Use Markdown
and Pandoc
If you are used to WYSIWYG editors such as Microsoft Word, you might
reasonably ask why you should use Markdown files. You can write your
document and format them any way you like, and you can export your
document to different file formats if you wish. For short documents that
you only need to format once and to one file format, you do not need
Markdown. I will argue that Markdown is still an excellent choice for such
documents, but it is for more advanced applications where it really shines.
For applications that are just as easy to handle with a WYSIWYG
editor, plain text can be a better choice in situations where you need to
share documents with others. A de facto file format for this is Word files,
but not everyone has Word. I don’t. I can import Word files into Pages,
which I have, and export to Word, but I don’t know what that does to
the formatting. Everyone has an editor that can work on plain files, and
with a plain text file, you know exactly what you are editing. If the text
and the formatting are separated, then someone with more artistic skills
can handle the formatting while I can write the text. One argument for
Word might be tracking of changes. This is an important feature, but with
plain text files, you can put them under real version control, for example,
GitHub, and that is superior to version tracking.
If you need your document in different formats, for example, you might
need to include your text in a printed progress report and also have it on a
T. Mailund, Introducing Markdown and Pandoc,
https://doi.org/10.1007/978-1-4842-5149-2_2

5

Chapter 2

Why Use Markdown and Pandoc

web site, then you can export the document to as many file formats as you
need. If you need different typography for the different file formats, you
might have to do substantial manual work. You might need to change all
the document styles by hand, and in the numerous occasions where you
need to make changes to your text, you need to change the styles for each
file format more than once. If you separate style and text, you avoid this
problem altogether.
Using a markup language to annotate your text makes it easier for you
to distinguish between the semantic structure of a document and how it is
formatted. In the Markdown document, you markup where headers and
lists are, for example, but not how these should be formatted in the final
output. The formatting styles are held in different files and you can easily
transform your Markdown input into all the output file formats and styles
you need. Furthermore, someone else can work on the style specification
while you concentrate on the text. Your Markdown doesn’t have to be
in a single file either. You can split it into as many as you want, and then
different authors can work on separate pieces of the text without worrying
about how to merge files afterward. With version control, you can even
work on the same file in parallel up to a point.

Separating Semantics from Formatting
Most documents have a semantic structure. Texts consist of chapters and
sections, plain text and emphasized text, figures and citations, quotes, and
lists. When we read a document, these semantic elements are visualized
by different fonts, bold and italic text, different font sizes, and we do not
directly see the semantic structure. Because we don’t immediately see the
structure, it is easy to forget that it is there.
Most word processors separate semantics from formatting. If you take
care to use the formatting section when working on a Word document,
then the semantic information needed to change styles, that is, the visual
6

Chapter 2

Why Use Markdown and Pandoc

Separating the semantics of a document from its formatting is not an
exclusive property of markup languages. However, when the separation
of text and semantics is not enforced, there is a potential for error. If you
decide to change the font size of level-two section headers, for example,
you can easily do this, but you can equally easy highlight a single section
this particular header different from all the rest, and if you later modify the
Great if this is on purpose; not great if this is not what you wanted.
With WYSIWYG editors, you can separate semantics from formatting,
but it is easy to break this separation. With markup languages, you can
also define some text elements as special and their format different from
related items, but you have to do this explicitly so you cannot easily do
this by mistake. Keeping the core text consisting of semantic elements and
separate from formatting is vital in many situations. If you want to translate
your text into both paper documents and web pages, you typically want the
format to be different in the two resulting documents. If the core text only
contains the semantic structure, this is quickly done, by having a different
mapping from semantic elements to formatting information, typically
called templates or stylesheets (see Chapter 9). With different stylesheets
for different output formats, the formatting is tied to the output text rather
than the input text (see Figure 2-1).

7

Chapter 2

Why Use Markdown and Pandoc
Markdown files
Output files

Pandoc

Templates &
style sheets

Figure 2-1. You can translate the text in multiple documents, or
multiple chapters that should be merged into a single document. You
combine these with templates for formatting the documents, and using
Pandoc you can combine it all to produce the documents you want.
Explicitly representing the semantic elements in the text, rather than
implicitly through how the text is formatted, is also essential if you want
all sections are marked up explicitly as sections, with headers at different
section levels, any tool can scan your document and identify these. If the
tools had to guess at the semantic meaning of text elements, based on how
the text was formatted, this would be a much harder task.
Using WYSIWYG word processors doesn’t prevent you from structuring
your documents as semantic units—they usually support this—but having
an explicit markup language makes it much easier to enforce.

Preprocessing Documents
If your documents are in plain text, you also get a lot of options for how
to process your document before you format it into a final output. There
are a large number of tools that will work well with plain text and let you
Preprocessing documents often require a few programming skills,
so it might not be the first thing you want to worry about if you are only
8

Chapter 2

Why Use Markdown and Pandoc

interested in writing text, but since the option is there, you can write your
text without worrying about processing it initially, and add such steps later.
I write a lot about R programming, and in those books, I have a lot of
code examples. Here, I use another preprocessor, one that lets me evaluate
the code when processing the documents so I know that all the code
examples work and so I can get the output of running code inserted into
the documents automatically before I create the output formats.
format your text, but the complexities are only there when you need them.
If you do not need a preprocessor, then you can ignore that they exist
altogether. If you do need preprocessing, then read Chapter 10.

W
 hy Markdown?
There are many different markup languages you can use. HTML (hypertext
markup language) is used for web pages. TeX and LaTeX are used for
many kinds of text documents but are especially powerful for typesetting
mathematics. Markdown is what we do on in this book.
What makes Markdown particularly pleasant to work with is its
simplicity. In HTML, for example, you need to structure your text using tags
that enclose every paragraph, every header, every list, and so on. When you
edit an HTML document, it is hard to separate the annotations from just
the text you want to write. LaTeX has the same problem. The annotation of
the text can be hard to ignore when you want to focus on writing.
Worse, if you write your documents in HTML or LaTeX, much of the
text is markup codes that specify the formatting. How much, of course,
depends on your document, but any markup instructions you make can
make the text difficult to read.
Consider this Markdown document:
# This is a level one header
This is a paragraph
9

Chapter 2

Why Use Markdown and Pandoc

## This is a level two header
Here is a paragraph that is followed by
* an unnumbered
* list
1. and a numbered
2. list that is
3. three items long
I hope you will agree that the markups here are minimal and that they
do not get in the way of reading or writing the text.
For comparison, the HTML version of the same text looks like this:
<h1>This is a level one header</h1>
<p>This is a paragraph</p>
<h2>This is a level two header</h2>
<p>Here is a paragraph that is followed by</p>
<ul>
<li>an unnumbered</li>
<li>list</li>
</ul>
<ol type="1">
<li>and a numbered</li>
<li>list that is</li>
<li>three items long</li>
</ol>
It is not terribly complicated, and after looking at it a bit, you can certainly
follow the structure of a document. It is far from as clean as the Markdown file.
The LaTeX version is slightly easier to read than the HTML file, but there
are still several formatting instructions that get in the way of just writing.
\section{This is a level one header}
This is a paragraph
10

Chapter 2

Why Use Markdown and Pandoc

\subsection{This is a level two header}
Here is a paragraph that is followed by
\begin{itemize}
\item an unnumbered
\item list
\end{itemize}
\begin{enumerate}
\item and a numbered
\item list that is
\item three items long
\end{enumerate}
Markdown is designed so you can annotate your text with semantic
information with little annotation clutter. It is designed such that reading
the input text is almost as easy as reading the formatted text. With
Markdown you don’t have quite the same power to control your formatting
as you do in a language like LaTeX, but the simplicity of Markdown more
than makes up for it.

Why Pandoc?
Since Markdown is just a language for adding structure to a text, it is not
tied to any particular tool. You can use any Markdown-aware software
when you want to process your documents. Many blogging platforms
will let you write your text in Markdown and automatically format it for
you. Translating Markdown into HTML was, after all, one of the primary
motivations for the language. Now, many text editors also support
Markdown and will support formatting in Markdown and exporting to
various file formats, usually with various formatting and style choices
determining what your output files will look like.

11

Chapter 2

Why Use Markdown and Pandoc

If your editor can export to different file formats and in different styles,
then that is obviously the easiest way for you to export your Markdown
text. With Pandoc, however, you have a lot of power over how your
documents should be processed. Pandoc is vastly more versatile than any
Markdown-aware text editor that I am aware of.
If you want to create a simple document with no fluff, it is easy to do so
with Pandoc, but easier to do from inside your editor. Try using Pandoc for
simple cases though, so you get familiar with the tool. When you get into
serious writing, and you want full control of how your final documents will
look, then you need the power of Pandoc. The learning curve can be steep,
but if you are familiar with using Pandoc for simple documents, then you
have a foundation to build on when you explore advanced features.

12

CHAPTER 3

Writing Markdown
If you have used plain text to write and share documents in the past, then
you are likely to be familiar with most Markdown markup annotations
already. Much of the syntax for Markdown is based on how people have
written plain text documents for years. This chapter covers the basic
Markdown annotations, which make up 99% of the annotations you will
use regularly. The notation I present in this chapter is supported by all
Markdown tools (as far as I am aware). The next chapter covers notation
that is not universally supported although many tools do support the
features there. All of them, of course, are supported by Pandoc.
If you write plain text with no special markup commands, as listed in
the remainder of this chapter, then the result will be plain text in the output
as well. One or more lines of text becomes a paragraph. If you need to start
a new paragraph, then use two new lines, that is, separate one paragraph
from the next with a blank line.

S
 ections
At the highest level, a text document is composed of its sections. Sections
come at different levels. In a book, the top level might be chapters,
the second level sections within the chapters, and the third level are
subsections within the sections.
a hashtag. Using one hashtag gives you a level-one header, which will
T. Mailund, Introducing Markdown and Pandoc,
https://doi.org/10.1007/978-1-4842-5149-2_3

13

Chapter 3

Writing Markdown

be a chapter in a book or a section in a smaller document. Two hashtags
give you a level-two section, a section if the first level is chapters or a
subsection if the first level is section. The next level sections have three
hashtags, and so on.
For the first two levels, you can alternatively underline the section titles
with = and -, respectively:
=================
----------------Any text you write following a header becomes the body of the section.
By default the headers are numbered. You can change this using
a template (see Chapter 9) or you can disable numbering on selected
## Another unnumbered header { .unnumbered }

E mphasis
We emphasize part of a text by putting it in italic or boldface. In Markdown
we use asterisks, ∗, to do this. To put a word in italic, we use one asterisk,
and to put it in boldface, we use two.
The preceding section, in Markdown, looks like this:
We emphasise part of a text by putting
it in italic or boldface. In Markdown
we use asterisks, \*, to do this.
14

Chapter 3

Writing Markdown

To put a word in italic, we use *one*
asterisk and to put it in boldface we
use **two**.
You will also notice that the first asterisk is escaped using a backslash.
That backslash prevents Markdown from interpreting the asterisks as the
beginning of an italic text.

Lists
You have two kinds of lists: numbered and unnumbered. To create a
numbered list, you put a number, followed by a period, at the start of a line
and write the list item after it. For the next list item, you go to the next line,
add another number, followed by a dot, and write the next item text. An
example could look like this:
1. This is a numbered list.
2. Where this is list item two.
3. And this is list item three.
The result will look like this:
1. This is a numbered list.
2. Where this is list item two.
3. And this is list item three.
The actual numbers are ignored, so you can get the same result if you
wrote:
10. This is a numbered list.
51. Where this is list item two.
42. And this is list item three.

15

Chapter 3

Writing Markdown

If you want your list items to span multiple lines, you need to indent
the lines following the number, like this:
1. This is a multi-line list item.
This is also part of the list item.
And so is this
2. Here is another one.
Where this is also part of the list item.
Doing that will give you this list:
1. This is a multi-line list item. This is also part of the
list item. And so is this.
2. Here is another one. Where this is also part of the list
item.
For unnumbered lists, you use an asterisk or a dash instead of
numbers; so you can write an unnumbered list like this:
* This is a numbered list
- Where this is list item two
* And this is list item three
•

This is a numbered list

•

Where this is list item two

•

And this is list item three

As you can see, you can mix asterisks and dashes, or stick to any
of the two you prefer. How the list is formatted when you create a
document is determined by the stylesheet and not which symbol you
use to create the list.

16

Chapter 3

Writing Markdown

If you want to have sublists under a list item, you can do this by
indenting the lines for the sublists. So you can write a list with a sublist
like this:
* This is a top-level list item
* Here is a sublist item
* Here is another
* Now we are at the top level again.
Just add sufficient spaces to put the sub-items under the enclosing
item. The result will look like this:
•

This is a top-level list item
–– Here is a sublist item
–– Here is another

•

Now we are at the top level again.

When you indent, you need at least four spaces or a tab per level.

Block Quotes
Should you need to add a quote to your text, you put a “>” before the
quoted text.
So you can write:
>
>
>
>
>
>
>
>

This is a blockquote. The blockquote
can span multiple lines. If you don't
put any new lines in it, you only
need to put the ">" at the beginning
of the line.
If you want multiple lines where you
include new lines, you should add
the ">" to each line.
17

Chapter 3

Writing Markdown

The result will look like this:
This is a blockquote. The blockquote can span
multiple lines. If you don’t put any new lines in it,
you only need to put the “>” at the beginning of the
line. If you want multiple lines where you include
new lines, you should add the “>” to each line.

Verbatim Text
Sometimes, you don’t want any formatting at all of a text; you want to leave
it verbatim as it is. When you want this, you can indent it with a tab (or four
spaces). You can write this:
This will be shown
absolutely verbatim
The result will then look like this:
This will be shown
absolutely verbatim
Sometimes, you also want to add verbatim text inline in a paragraph.
To achieve this, simply put the verbatim text in backticks. So you can write
'this' to achieve this.

Markdown was initially written to make it easier to write content for web
pages. Consequently, it has built-in syntax for inserting hypertext links.
These will work both with links to web pages and for cross-references

18

Chapter 3

Writing Markdown

You have two options for specifying a link: you can put the destination
URL where you insert the link, or you can create a label and map it to the
URL so you can refer to the label when you insert a link. To put the URL
where you insert the link, you put the text you want to be the link in square
brackets and the destination URL for the link in round parentheses right
after. You would write a text like this:
This is a link to [my blog](http://www.mailund.dk).
This is fine for most cases, but if you have many links in a paragraph,
then the link annotations start interfering with how easy it is to read the
text. Instead, you can give the destinations a shorter name and put the
destination later in the text. To do this, you replace the round parentheses
with square brackets, like this:
This is a link to [my blog][blog].
Then, later in the text, you define what the link should point to like this:
[blog]: http://www.mailund.dk
You use the same syntax to make hypertext links within your
document. The simplest way to create a link to a section is to leave out the
destination but put the name of the section in square brackets. A link to
this chapter would then be written like this:
This is a link to the [Writing Markdown] chapter.
This, of course, will not work if you want the link to contain a different
text than the section name, or if you have several sections with the same
name. You can work around this by giving the section headers explicit
labels. These, you put in curly brackets after the section header. You can
assign a label to a header like this:

19

Chapter 3

Writing Markdown

The hashtag is needed here and is also necessary when linking to the
section. The hashtags are used in HTML to refer to sections of a web page,
and it is from there that Markdown gets its syntax. To link to the section we
have labeled this way, we would write the link like this:
Links are only handy for hypertext documents, and in standard
Markdown, you cannot make cross-references to figures or tables or any
non-section elements. In Pandoc you can, using an extension, but we
cover that in Chapter 7.

I mages
To insert figures in your document, you use a syntax similar to inserting
links. The difference is that you need to put a bang, “!”, before the link.
![Title of the figure](URL-to-figure)
Typically, you will have the figures as local files and there you use the
path to the figure file, either relative to where you build your document or
as an absolute path.
![Title of the figure](path-to/my-figure)

E xercises
In the following text are a few exercises where you can test yourself on the
material covered previously. If you use an editor that can immediately
show you the result of a Markdown text, then test your results there.
Otherwise, put your answers aside until we have covered how to format
Markdown in Chapter 5.

20

Chapter 3

Writing Markdown

Sections
Write a document with three level-two sections and with two level-three
sections inside each. Remember that the number of # determines the
section level. Make them both numbered and unnumbered.

Emphasis
Write this text in Markdown.

Lists
Take the three items
•

one item

•

two items

•

three items

and write them as a numbered and an unnumbered list.
Now, put
•

four items

•

five items

as a sublist under one item.

Block Quotes
Make the following text a block quote:
This is a text that we want to put in block quotes.

21

Chapter 3

Writing Markdown

Write a text and insert a link to a web page and to a section in your text.

Images
Find an image file and insert it into a text.

22

CHAPTER 4

Pandoc Markdown
Extensions
Markdown is, unfortunately, not standardized. Different tools will support
different markup syntax and process them differently. The Markdown
described in the previous chapter will work in most, if not all, tools. The
table syntax is usually less well supported, but the rest of the markup will
ordinarily work.
Pandoc provides several extensions to the Markdown language
described in the previous chapter. In this chapter, we will see some
useful extensions for lists and tables. To get a complete list of Pandoc
extensions to Markdown, you should consult the Pandoc documentation
at https://tinyurl.com/y87mstzf.

L ists
Generally, the numbers you use when you write an ordered list are
ignored. They are used to indicate list items, but the actual numbering
does not matter. This makes it easier to insert a new item in the middle
of a list, which is a good thing, but sometimes you want to start a list at a
different number than one, and in that case, basic Markdown can’t help

T. Mailund, Introducing Markdown and Pandoc,
https://doi.org/10.1007/978-1-4842-5149-2_4

23

Chapter 4

Pandoc Markdown Extensions

you. With Pandoc, though, lists start with the number you give the first
item in a list. So you can start a list at number three like this:
3. This lists start at number three.
5. Although we used "5." to start this
item, it still gets the number 4.
The numbers in the following list items are still ignored. The result will
look like this:
3. This lists start at number three.
4. Although we used “5.” to start this item, it still gets
the number 4.
This is a good way to continue lists, but you will have to update the
initial number when you have added or removed items in the previous list.
To automatically make a list continue at the next number, even when
you changed a previous list, you can use the special symbol “@”. This works
just as a number when you use it in a list, and it always counts from where
you left off. So you can write something like this:
(@) Starting a list
(@) Continuing the list
Here is some text that doesn't
belong to the list.
(@) This continues the list,
numbered from where we
left off the list.
(@label) This item is labelled
so that we can refer back
to it. Like this: see item
(@label).

24

Chapter 4

Pandoc Markdown Extensions

The result will look like this:
(1) Starting a list
(2) Continuing the list
Here is some text that doesn’t belong to the list.
(3) This continues the list, numbered from where we
left off the list.
(4) This item is labelled so that we can refer back to it.
Like this: see item (4).
This can be very useful for lists of examples or such, but the “@”
counter is global so you cannot restart the counter. Unfortunately, there
is currently no support for both automatically numbered items and
restarting counters.
In this example, we also saw another feature of Pandoc. We do not
have to write a number followed by a dot. In the previous example, we put
numbers—represented by @—in parentheses, and the result was a list that
used parentheses. You can also use a single closing parenthesis:
1) This is a
2) list
3) it really is
It will give you this list:
1) This is a
2) list
3) it really is
If you make lists using a number and a period, you get the standard
numbered lists, but you can also use letters or Roman numerals just by

25

Chapter 4

Pandoc Markdown Extensions

starting the list with such. If you want to use parenthesis instead of periods,
you can also do this. You can, for example, create a list like this:
a. This list uses letters instead of numbers.
b. We can make a sublist with roman numerals:
i. This sublist also uses parenthesis
ii. Cool, isn’t it?
The source markup for that list looks like this:
a. This list uses letters instead of numbers.
b. We can make a sublist with a roman numerals:
i. This sublist also uses parenthesis
ii. Cool, isn’t it?
You can mix the different list notations so you have different list formats
as sublists, but if you mix them at the same level, you will start a new list.
Lists are frequently used to define terms or concepts, and in Pandoc
you can create definition lists by following a term with a colon and
indenting the start of the definition with a tab or at least four spaces. So
you can create definition lists like this:
Something we want to define. Definition of the thing
As long as we indent the following lines, they become part of the
definition.
Here starts the next thing we define. Here we write the definition.
More of the definition
The syntax for creating this list is this:
Something we want to define.
:    Definition of the thing
As long as we indent the following lines, they
become part of the definition.
26

Chapter 4

Pandoc Markdown Extensions

Here starts the next thing we define.
:    Here we write the definition.
More of the definition
An alternative syntax uses tildes, “~”, instead of colons:
Term 1
~ Definition 1
Term 2
~ Definition 2a
~ Definition 2b
Term 1 Definition 1
Term 2 Definition 2a
Definition 2b
Either syntax will do.

Tables
To add tables to a document, you can mark up the columns using dashes.
You can write a table like this:
Right    Left     Center    Default
-------    ------ ----------  ------     12    12        12
12
123    123
123         123
1    1         1            1

27

Chapter 4

Pandoc Markdown Extensions

The result will look like this:
Right

Left

Center

12

12

12

12

123

123

123

123

1

1

Default

1

1

How you align the elements in the columns determine how you align
the headers above the dashes. If the text is to the right, the column will be
right-aligned. The same for left and center alignment, if the text is on the
left or in the middle, the table column will be left-aligned or centered. If
you start the header at the same position as the dashes, you get the default
alignment, which is left alignment.
You can leave out the headers, but then you need to repeat the dashes
at the end of the table as well.
-------    ------ ---------- ------     12    12        12         12
123    123
123        123
1    1         1
1
-------    ------ ---------- ------12

12

12

12

123

123

123

123

1

1

1

1

If you do not provide a header, the alignment is determined by the
first line in the table. In the preceding example, in the last column, the
reason it isn’t right-aligned is that there is a space after the first number
in the column before the end of the dashes that specify the column. Move
the first number one position to the right, and that column would also be
right-aligned.
28

Chapter 4

Pandoc Markdown Extensions

Tables are the Markdown markups with the least consistent support in
different tools. The table syntax described often frequently works, but in
the two editors I use for writing my books, they are not supported. In all the
Markdown viewers I am familiar with, though, they display correctly.
In Pandoc, there is excellent support for tables, and Pandoc provides
some extensions to table markup beyond the preceding notation.
For figures, you can add captions using the link syntax. For tables,
you have no similar syntax. You can, however, add a caption to a table
using “Table: Caption” following the table. So you can create a table with a
caption like this:
-------     ------ ---------- ------     12     12
12
12
123     123      123      123
1     1          1          1
-------     ------ ---------- ------Table: This is a caption
The result looks like this:
Table 4-3. This is a caption
12

12

12

12

123

123

123

123

1

1

1

1

You can leave out the “Table” part if you want; just having the colon
will give you a caption.
If you want table cells to span multiple lines, you can do this as well.
For multi-line tables, you must put a row of dashes before the header
(unless you don’t have a header), you must end the table with a row of

29

Chapter 4

Pandoc Markdown Extensions

dashes and then a blank line, and you must separate rows by a blank line.
This example, from the Pandoc manual, shows how this works:
----------------------------------------------------  Centred   Default      Right Left
----------- ------- ---------- ---------------------    First   row          12.0 Example of a row that
spans multiple lines.
Second   row            5.0 Here's another one.
Note the blank line
between rows.
----------- ------- ---------- ---------------------The result will look like this:

Default Aligned

Right Aligned

Left Aligned

First

row

12.0 Example of a row that spans
multiple lines.

Second

row

5.0 Here’s another one. Note the
blank line between rows.

You can leave out the header, but then you must repeat the dashes that
define the columns after the table, followed by a blank line.
----------- ------- ---------- ---------------------   First    row         12.0 Example of a row that
spans multiple lines.
Second    row            5.0 Here's another one.
Note the blank line
between rows.
----------- ------- ---------- ----------------------

30

Chapter 4

Pandoc Markdown Extensions

Result:
First

row

12.0

Second

row

5.0

Example of a row that spans multiple lines.
Here’s another one. Note the blank line between rows.

An alternative syntax for tables uses plain text grids to separate
columns. An example, with a header, looks like this:
+---------------+---------------+--------------------+
| Right         | Left          | Centered          |
+==============:+:==============+:==================:+
| Right         | Left          | Centered          |
+---------------+---------------+--------------------+
Result:
Right

Left

Centered

Right

Left

Centered

Without headers, it looks like this:
+--------------:+:--------------+:------------------:+
| Right         | Left          | Centered          |
+---------------+---------------+--------------------+
Result:
Right

Left

Centered

For these types of headers, the colons determine the alignment. Put
a colon at the end of the “=” or “-” of the cell-border to get right-aligned
columns, at the left to get left-aligned columns, and at both ends to get
centered columns, and leave them out for the default alignment.

31

Chapter 4

Pandoc Markdown Extensions

You can also use pipes, “|”, to specify the columns. Then, the syntax will
look like this:
| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |
Result:
Right

Left

Default

12

12

12

12

123

123

123

123

1

1

1

Center

1

S
 mart Punctuation
Proper text typography uses different types of dashes—hyphens in
words, en-dashes for numeric intervals, and em-dashes for parenthetical
sentences and emphasis. Quotes are usually different at the beginning and
end of a text in quotation marks. Three dots are different from ellipses.
Many word editors will automatically substitute some dashes and translate
straight quotes into the correct form, but not all. Since you are writing
Markdown in plain text, and since most keyboards do not give you access
to all typographic symbols, Pandoc can help you out with getting these
symbols. To enable this, you need to call Pandoc with the option --smart
(we see how to invoke Pandoc in Chapter 5).
If you turn on smart punctuation, quotes will be handled correctly,
three dots will be translated into ellipses, a single “-” will be a hyphen, two
dashes will give you an en-dash, and three dashes will give you an em-dash.

32

Chapter 4

Pandoc Markdown Extensions

F ootnotes
You can insert footnotes in your text using a syntax resembling links and
images. For footnotes, you need to add a caret, (ˆ). To put the footnote
inside the text paragraph you are writing, you add a caret and then the
footnote text in square brackets.
Footnote inside a paragraph.^[This is the footnote.]
Since footnotes tend to interfere with the main text, you can give
them a label and add the text elsewhere. When you do this, you name the
footnote and put the name in the main text.
Reference to a footnote.[^footnotelabel]
When you add a footnote this way, the caret has to go inside the
brackets. If it goes before the brackets, you are adding the footnote inside
the text.
Somewhere the text you must define what a footnote label refers to.
The syntax is the same as the one for defining links you can refer to inside
the text, except that for defining footnotes the name must start with a caret.
[^footnotelabel]: This is footnote two.
If you want it to cover multiple lines, you
have to indent the following footnote lines.
by at least four spaces.
The output of the two approaches should look like this: Footnote
inside a paragraph.1
Reference to a footnote.2
 his is footnote one.
T
This is footnote two.
If you want it to cover multiple lines, you have to indent the following footnote
lines by at least four spaces.

1
2

33

Chapter 4

Pandoc Markdown Extensions

Exercises
Lists
Write a list with five items. Between two and three, add a paragraph of text,
but make sure that the numbers continue with four.
Add a label to item three and refer to it in item five. Create a list of
definitions as well. Make them multi-line.

Tables
Make a table with three columns where you left-justify the first column,
center the second column, and right-justify the third.
Write a table with a caption. Until we format the Markdown with
Pandoc in the next chapter, you will not see the result but keep the text so
you can test it there

Footnotes
Write a text with a footnote. Use both notations for footnotes.

34

CHAPTER 5

Translating
Documents
Once we have a document written in Markdown, we want to translate it
into other file formats using Pandoc. First, though, we have to download
Pandoc. Go to Pandoc’s installation guide at http://pandoc.org/

F ormatting a Markdown Document
with Pandoc
For our first example, we can take the small Markdown document shown
here:
# This is a test document
Here is some text in the document.
* This is a list
* With two items
If we save this Markdown document in a file called input.md, we can
translate it into an HTML file, output.html, using the command:
pandoc -o output.html input.md
T. Mailund, Introducing Markdown and Pandoc,
https://doi.org/10.1007/978-1-4842-5149-2_5

35

Chapter 5

Translating Documents

The -o option specifies the output file. The input.md file is specified
without any options. You do not need any options for input files, and you
can provide more than one. If you provide more than one input file, they
are in effect concatenated before Pandoc processes them, so if you want
to construct a book from several chapters you have written in separate
files, you can provide them on the command line in the order you want the
chapters to appear in the book.
Pandoc figures out the input and output format from the file
extensions, so if you use the preceding command, it will know that the
input is Markdown (filename suffix .md) and that the output should be
HTML (filename suffix .html). You can make the format of input and
output formats explicit. You can use the option --from to specify the input
format and --to to specify the output format. In most cases, you will not
need to specify the formats—the filenames contain all the information you
need—but sometimes different formats share the same filename suffixes,
such as the EPUB and EPUB3 formats that both use filename suffix .epub.
In those cases, you need the options.
If you specify the input and output document format, then you can also
treat pandoc as a program you can pipe input into and get the formatted
document out from. You could, for example, write
cat input.md | \
pandoc --from markdown --to html \
> output.html
In itself there is little use for this, but combined with preprocessing
(Chapter 10) and filters (Chapter 11), it is very handy.
Back to the output of pandoc. If you run the previous command
pandoc -o output.html input.md

36

Chapter 5

Translating Documents

in your terminal, then the output.html file should now contain the
following HTML:
<h1 id="this-is-a-test-document.">
This is a test document
</h1>
<p>Here is some text in the document.</p>
<ul>
<li>This is a list</li>
<li>With two items</li>
</ul>
If you are not familiar with HTML, this might not be readable, but I hope
that you can at least recognize the elements from the input Markdown.
This HTML is not a complete HTML file. It is a fragment of an HTML
file that corresponds to the Markdown document, but it is missing header
and footer markup that is needed for a complete HTML page. Per default,
Pandoc creates HTML markup that can be added to a web page, but not
standalone documents. To get the header and footer added as well, you
can use the option --standalone.
pandoc --standalone -o output.html input.md
The --standalone option is needed for HTML output if you want a
complete document. If you choose an output format that is typically not
meaningful as a fragment, such as PDF documents (suffix .pdf), EPUB
documents (suffix .epub or .epub3, or Word files (suffix .docx), Pandoc
will automatically create complete documents, and the --standalone
option is not needed.
If you run pandoc --standalone -o output.html input.md, you will
get a warning:
[WARNING] This document format requires a nonempty
<title> element.
37

Chapter 5

Translating Documents

Please specify either 'title' or 'pagetitle' in
e.g. by using --metadata pagetitle="..." on the
command line.
Falling back to 'input'
But despite the warning, you will get an HTML document that contains
all the elements such a document needs:
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml"
lang="" xml:lang="">
<meta charset="utf-8" />
<meta name="generator" content="pandoc" />
<meta name="viewport"
content="width=device-width,
initial-scale=1.0,
user-scalable=yes" />
<title>input</title>
<style>
code{white-space: pre-wrap;}
span.smallcaps{font-variant: small-caps;}
span.underline{text-decoration: underline;}
div.column{display: inline-block;
vertical-align: top; width: 50%;}
</style>
<body>
<h1 id="this-is-a-test-document">
This is a test document
</h1>

38

Chapter 5

Translating Documents

<p>Here is some text in the document.</p>
<ul>
<li>This is a list</li>
<li>With two items</li>
</ul>
</body>
</html>
There is more general HTML here than there is in our text, but luckily
we do not need to worry about it; we can focus on the Markdown and let
The warning we got has to do with the title we get in the line
<title>input</title>
Pandoc just took the name from the input file but was hoping to get
the title explicitly provided. You can do this using metadata; see Chapter 8.
Ignore it for now.
You can try making different output formats with the commands
pandoc
pandoc
pandoc
pandoc

-o output.pdf input.md
-o output.docx input.md
-o output.epub input.md
--to=epub3 -o output.epub input.md

In the last example, we explicitly specify that the EPUB format to use in
the output is EPUB3.
Another case is where we might want to specify the --to format is for
PDFs. By default, Pandoc will create PDF files using LaTeX, but you can
specify that it should use ConTeXt instead with the command:
pandoc --to=context -o output.pdf input.md

39

Chapter 5

Translating Documents

To get a complete list of supported input and output formats, run the
commands
pandoc --list-input-formats
and
pandoc --list-output-formats
respectively.
Pandoc can translate between many different input and output
formats, but in this book, we will only consider Markdown input and how
to translate Markdown to other formats.

Frequently Useful Options
There are many options you can use to influence how Pandoc transform a
document. I refer you to the online manual1 for a full list. Here, I will list a
few that I find particularly useful in my own writing.

S
 ections and Chapters
First, we consider options that relate to how sections are interpreted.
In Markdown we specify the different levels of section headers by the
number of hashtags, but when we produce a document, we sometimes
have to worry about whether the top-level sections are parts, chapters,
or sections. If we are writing a short report or paper, we want the levelone headers to start sections, but if we are writing a book, we want them
to start chapters. The default depends on the output we produce, and
Pandoc does some guessing for us, but you can choose explicitly what

http://pandoc.org/MANUAL.html

1

40

Chapter 5

Translating Documents

the top level should be using the --top-level-division option. For my
books, where I want the level-one headers to be chapter headers, I use
--top-level-division=chapter.

option --toc or the option --table-of-contents; the first is just a shorter
version of the second. You can specify the level of sections you want in the
--toc-depth=1. When I produce PDF, I am happy with the default. You can
play around with the option to see what you prefer.

Image Extensions
If you want to produce both PDFs and ebooks from your Markdown input,
you might want to use PDF vector graphics for figures for the PDF output
but bitmap PNG for the ebook version. Using bitmap graphics for the
PDF output means you have to worry about the resolution, but using PDF
graphics for ebooks doesn’t always work. When you insert images into
![Figure caption](graphics-file)
syntax, you need to specify the input file name, but if you want to produce
both ebooks and PDFs, you don’t want to have to change all the file names
depending on which output format you are producing.
You can leave out the filename suffix for graphics files and specify the
desired suffix using the
--default-image-extension

41

Chapter 5

Translating Documents

option instead. Then, for any graphics file where you haven’t explicitly
written the filename suffix, Pandoc will use the default. I always use
--default-image-extension=pdf
when producing PDF documents and
--default-image-extension=png
when producing ebooks.

E book Covers
Ebooks contain cover images together with their text. If you produce
ebooks, you want to specify the cover image as well. You can do this
using the --epub-cover-image option. If your cover image is in the file
cover.png, you write
--epub-cover-image=cover.png

U
 sing Makefiles
For this book, I have all my text in a single book.md document. This is fine
for a short book like this one, but usually, I keep each chapter in a separate
file. The command line for compiling my books can get rather long, and
I often have various options for different output formats that I need to
remember, so if I had to use the command line each time I wanted to build
a new version of a book, it would quickly become tedious and extremely
error-prone. So I use Make (https://tinyurl.com/nyc2ec2) for compiling
my books.
If you are not familiar with Make, I will give you sufficient detail for
to read the Makefile I give as an example, and maybe a starting point for
your own Pandoc Makefile, but introducing Make in full detail is beyond

42

Chapter 5

Translating Documents

the scope of this book. Many programs solve the same problem that Make
does, so there are alternatives to choose from if you do not like Make.
The Makefile I use is not sophisticated and it suffices to know this:
1. You define a variable by writing
VARIABLE_NAME := VALUES
2. You refer to the value that a variable holds using
$(VARIABLE_NAME) 3. When you write target: dependencies you say that of you want to have target and then, if any of the dependencies have changed since lasts time you constructed target then you need to construct it again. If dependencies of dependencies have changed, then you need to build the dependencies and then the target. And so on. 4. The lines after target: dependencies that are indented by a tab are the instructions your computer needs to make target. 5. The first target: dependencies line in the Makefile is the target that Make will handle if you do not provide another target on the command line. The Makefile I use for this book looks roughly like this (although I have left out a few options). I will walk you through it here. CHAPTERS := header.yml book.md PANDOC := pandoc OPTS_ALL := --toc --smart \ --top-level-division=chapter 43 Chapter 5 Translating Documents PDF_OPTS :=$(OPTS_ALL) \
--default-image-extension=pdf
EPUB_OPTS := $(OPTS_ALL) \ --default-image-extension=png \ -t epub3 --toc-depth=1 \ --epub-cover-image=cover.png all: book.pdf book.epub book.docx book.pdf:$(CHAPTERS) Makefile
$(PANDOC)$(PDF_OPTS) -o $@$(CHAPTERS)
book.epub: $(CHAPTERS) Makefile$(PANDOC) $(EPUB_OPTS) -o$@ $(CHAPTERS) book.docx:$(CHAPTERS) Makefile
$(PANDOC)$(PDF_OPTS) -o $@$(CHAPTERS)
clean:
rm book.pdf book.epub book.docx
I use a variable to hold the input files. Just the header and the single
Markdown file in this case. You can specify metadata (see Chapter 8) on
the Pandoc command line or in a YML file. You can put the metadata in
your Markdown text, but then it has to be at the top of the input, and you
cannot translate a single chapter without including the first one. I prefer to
put my metadata in a separate file, which in this case is header.yml.
I only have one Markdown file for this book. I am writing this in the
Ulysses editor where I can split the book into different sections but export
it as one combined file. Since the partition into chapters and sections is
kept in Ulysses and not in separate files, I do not have a file per chapter.
I put the input files in the variable CHAPTERS. If you have several, you
can add it to the CHAPTERS variable. I keep the Pandoc command tool in a
variable as well. I have more than one version installed, and I can switch
44

Chapter 5

Translating Documents

between them by updating the variable. After that, I put the arguments
that all Pandoc runs share in OPTS_ALL and then PDF and EPUB-specific
options in PDF_OPTS and EPUB_OPTS. I make a Word document, but I can
use the PDF arguments for this; Pandoc will know how to make a Word
document with the same options as used for the PDF. Next is all the targets,
dependencies, and commands for making the targets. The targets all and
clean are special. The first doesn’t build anything; it just triggers a build of
its dependencies—so it is indirectly building these—which are the three
book formats the Makefile knows how to make. The clean target doesn’t
have any dependencies, but it will delete the books we generate with the
middle three commands.
I then define some options I want to use for all output formats and
then options that I only want to use for PDF and others I only want to use
for ebooks. In the metadata I set for PDF output, I could also have put in
the header—they wouldn’t interfere with the EPUB output if I did—but I
have chosen to set them here.
I build an EPUB book in the Makefile, but if you are planning to
publish on iBooks, I do not recommend using this file. I find it much
easier to format and submit a book using Pages. Pages can read the Word
document, and that is how I usually submit a book to iBooks: I make a
Word document, open it in Pages, and then submit it. You might think that
building a book in the right format and then use iTunes Connect to submit
it would be easier. You would be wrong. If you want to publish on Amazon
(on Kindle Direct Publishing), you are also better of using their tool Kindle
Create. Kindle Create can read the Word file, and you can submit from
there. There is a command line tool that can translate from EPUB to the
MOBI file format used on Kindle, but Kindle Create is easier to use.

45

CHAPTER 6

Math and Computer
Programming
Languages
You might not be in the habit of writing technical or scientific text,
but if you are, then Pandoc supports both mathematics and computer
programming code formatting.

W
 riting Math
Pandoc has some excellent support for writing math as long as your
output file format supports it. Word files have built-in support for math,
and Pandoc will use this if the output file is a Word document. With PDF,
Pandoc uses LaTeX as an intermediate format, and LaTeX is spectacularly
perfect for math. With HTML and EPUB, you have some math support
depending on the version and libraries you use to display the math.

T. Mailund, Introducing Markdown and Pandoc,
https://doi.org/10.1007/978-1-4842-5149-2_6

47

Chapter 6

Math and Computer Programming Languages

For HTML and EPUB, you have different options for how the output
should handle math. I usually use either MathML1 or MathJax2 when I have
math in HTML or EPUB documents. For MathML you can use the option
--mathml:
pandoc --mathml -o document.epub document.md
For MathJax, you need to produce EPUB3 documents to get it to work,
so you must specify the output format as well:
pandoc --to=epub3 --mathjax \
-o document.epub document.md
With either option, you get an EPUB document that displays the math
well. Not as beautiful as in PDF documents, where LaTeX handles the
math, but reasonably well.
The way you write math in your document is by inlining TeX syntax.
The math in output documents will only be TeX if you output a LaTeX file
or go through LaTeX when building a PDF file, but the de facto standard for
how to write math in plain text is TeX, so that is what Pandoc uses.
You start and end math using dollar signs. If you use one, you get inline
math, and if you use two, you get “display” math, which means you get the
math on a single line and centered. This is inline math: $\int_aˆb x\, b \mathrm{d}x$ looks like òx dx. You write display mode math between
a

double dollar signs, so this
$$\sum_{j=1}^N \frac{1}{j^2}$$
will result in this:
N

1

åj
j =1

w ww.w3.org/Math
www.mathjax.org

1
2

48

2

Chapter 6

Math and Computer Programming Languages

Pandoc supports a large subset of math you can write in LaTeX.
For example, here is a more complex equation:
ì
ï
ï
ïi
j=0
ïï
d ( i, j ) = í j
i=0
ï
ìd ( i - 1, j - 1) + 1( i ¹ j ) i > 0, j > 0
ï
ïmin ïíd ( i, j - 1) + 1
ï
ïd ( i - 1, j ) + 1

ïî
î
The LaTeX code looks like this:
$$d(i,j) = \begin{cases} \,i & j = 0 \\ \,j & i = 0 \\ \,\min\begin{cases} d(i-1,j-1) + \mathrm{1}(i\neq j) \\ d(i,j-1) + 1 \\ d(i-1,j) + 1 \end{cases} & i>0,j>0 \end{cases}$$
If you write math that Pandoc cannot handle, for example, if you use a
LaTeX package that Pandoc does not know about, then you can just write
the LaTeX code anyway. What Pandoc doesn’t understand it passes on to
the output. So, as long as your output is a format that goes through LaTeX,
you are good to go.

49

Chapter 6

Math and Computer Programming Languages

If your output is HTML or EPUB where you use MathML or MathJax,
then you can also write an equation that should be passed along verbatim
to the output.
If you have a single document but want separate equations for different
output formats, you cannot just let the text fall through to the output.
There, you need to output one version for one output format and another
for another format. Here, Pandoc lets you write verbatim text that will only
be included for a specific output format. You can write
{=latex}
$$\sum_{j=1}^N \frac{1}{j^2}$$

for a block of text that should only be included if the output is LaTeX and
write
$f(x)=x^2${=latex}
for inline text.

Writing Code Blocks
Markdown is frequently used by programmers to write about programs, so
not surprisingly it has support for displaying code examples, typically with
formatting to syntax highlight the examples. This support varies between
different tools, but Pandoc has terrific support for many programming
languages.
The syntax for writing a block of code uses either tilde, “~”, or backticks,
“‘”. Of these, backticks are more likely to be supported by other tools; so,
I will use these here. Every example I give in the following will also work if
you use ~ instead of a backtick.
You start a block with three backticks, then write your code, and then
end the block with another three backticks.
50

Chapter 6

Math and Computer Programming Languages

for (int i = 0; i < n; i++) {
printf("%d\n", i);
}

You can also use tiles instead of backticks, but I will use backticks in
this chapter.
~~~
for (int i = 0; i < n; i++) {
printf("%d\n", i);
}
~~~
If you only use backticks or ~, you get a verbatim text block, just as if
you had indented the text. To get syntax highlighting, you must also inform
Pandoc of which programming language you are using. You can do this by
writing the name of the language after the first line of backticks. To syntax
highlight the preceding code, which is written in C programming language,
you would write
c
for (int i = 0; i < n; i++) {
printf("%d\n", i);
}

The result will look like this:
for (int i = 0; i < n; i++) {
printf("%d\n", i);
}

51

Chapter 6

Math and Computer Programming Languages

A block of Python code would look like this:
python
for i in range(n):
print(i)

The result would look like this:
for i in range(n):
print(i)
To get a complete list of supported programming languages, you can
run the command
pandoc --list-highlight-languages

Code Block Options
This syntax for displaying code is supported by many web sites where it is
usual to write code in text, such as on GitHub. You can give more advanced
instructions for how code should be displayed, but then you need to use
a slightly different syntax that is more Pandoc specific. There, you put
instructions in curly brackets after the first three backticks. You must
specify the programming language but prepend a dot to the name, for
example, write .python for Python. You can then number the code lines
with the instruction .numberLines:
{.python .numberLines}
for i in range(n):
print(i)

52

Chapter 6

Math and Computer Programming Languages

The result will look like this:
1   for i in range(n):
2       print(i)
You can specify which line number to start from with the option
startFrom. To start from line 100, we can write
{.python .numberLines startFrom=100}
for i in range(n):
print(i)

The result will look like this:
100  for i in range(n):
101      print(i)
You can give the code block an identifier:
{#my-code .python .numberLines}
for i in range(n):
print(i)

This will make the code block a hypertext target (an anchor in HTML),
so you can create hypertext references to it. The anchor id is the same as
the identifier excluding the hashtag. That is, in the preceding example, it
is my-code. You refer to the target as you would with other references in a
Markdown document, for example:
{#my-code .python}
for i in range(n):
print(i)

See [my code](my-code)
53

Chapter 6

Math and Computer Programming Languages

In HTML output, you can also make each line an anchor using the
option .lineAnchors.
{#my-code .python .numberLines .lineAnchors}
for i in range(n):
print(i)

The line identifiers are the code block id followed by the line number.
In this case, the two lines my-code-1 and my-code-2.
class of the <pre> block that contains the code. With a stylesheet, you can
easily make code blocks formatting distinct. In filters (see Chapter 11),
you can use the options for arbitrary transformations or calculations. One
crucial thing to keep in mind if you start using code block options to a
larger extent is that all options without arguments
.python
.numberLines
must start with a dot, and all options that take an argument
startsFrom=100
cannot start with a dot. If you break these rules, Pandoc will not do what
you want.

Syntax Highlighting Styles
The syntax highlighting scheme is controlled by variations of stylesheets:
cascading style sheets (CSS) for HTML output and a set of \newcommand
options for LaTeX (and thus PDF) output. These highlighting instructions
are put directly in the output file (when you make a standalone
document) and are thus not easy to override. You can, however, choose
54

Chapter 6

Math and Computer Programming Languages

from a list of predefined highlighting styles. You can see the complete list
by running the command
pandoc --list-highlight-styles
You select a style using the --highlight-style option. When I build
print versions of my books, I want a black-and-white output, so I use the
option
pandoc --highlight-style=monochrome
This gives me a black and white highlighting using italic and boldface
to display different language components. You can also completely
disable syntax highlighting while still using code blocks, using the option
--no-highlight.

Exercises
Code blocks
Write the Markdown to display this Python code:
print("hello, world")
for i in range(10):
print(i)

Code Block Options
Now add line numbers to it

Syntax Highlighting
Format the code in at least three different highlight formats and check the
results.
55

CHAPTER 7

Cross-referencing
Cross-referencing is not directly supported by standard Markdown.
Markdown was mainly invented to write hypertext documents for web
pages, so referencing section numbers, figures, or tables is not part of it. We
can use the link syntax to make hypertext references to sections but not get
section numbers and such.
Pandoc itself doesn’t support extensions for other kinds of cross-
referencing, but there is a so-called “filter,” pandoc-crossref, that adds
this support. Filters (see Chapter 11) are scripts that are run to modify a
document after it has been parsed by Pandoc and before the output format
is generated. Filters are beyond the scope of this book, but we will use two
in this and the next chapter.
The pandoc-crossref filter is not necessarily automatically installed
when you install Pandoc, so you might need to install it manually. How
you do this will depend on your platform. I work on MacOS and use the
Homebrew1 package manager, so I installed it using
brew install pandoc-crossref
The filter is a Haskell package, so you can also install it using the cabal
package manager if you have the Haskell system installed.
cabal update
cabal install pandoc-crossref

http://brew.sh

1

T. Mailund, Introducing Markdown and Pandoc,
https://doi.org/10.1007/978-1-4842-5149-2_7

57

Chapter 7

Cross-referencing

It might take a little while.
If you installed Pandoc using any of the packages from the Pandoc
releases web page,2 the filter should already be included. If all else fails,
you can download the source code and compile it at the pandoc-crossref
homepage.3
To invoke the filter when processing a document with Pandoc, you
use the option --filter (or -F as a shorter option). To enable the pandoc-
crossref filter, run Pandoc as
pandoc --filter pandoc-crossref
Cross-referencing using pandoc-crossref uses a syntax similar to
hypertext links, but with a twist. You specify labels with curly brackets
and insert references to them using square brackets. You need to include
cross-referencing type as part of the labels, though. To insert a label,
you use the syntax {#type:label}, and to refer to it, you use the syntax
[@type:label]. The type, here, specifies whether you are referring to
sections, tables, figures, or equations.

R
 eferencing Sections
Using cross-referencing via links works well for HTML or EPUB
documents, where you have hypertext, but less well for printed media,
where you don’t. There, you would make references to chapters and
sections using their numbers instead, but that isn’t supported in standard
Markdown.
Using pandoc-crossref, we can refer to sections via section numbers.
We need to define labels for the headers we want to refer to, and these

h ttps://github.com/jgm/pandoc/releases

2
3

58

Chapter 7

Cross-referencing

header labels must have). We can then insert cross-references to section
numbers using [@sec:label] markup. An example could look like this:
# This is a chapter {#sec:chapter}
## This is a section {#sec:section}
See [@sec:chapter] and [@sec:section].
Pandoc doesn’t number sections by default, and while it will number
sections in some formats when we use pandoc-crossref, we should use
the option --number-sections to make sure. If, for example, you generate
PDF output, sections will not be numbered if you leave out this option, and
consequently, it makes no sense to refer to sections by their numbers.
pandoc --number-sections \
--filter pandoc-crossref \
-o output.pdf \
input.md
This approach will use the LaTeX section numbering system for PDF
output but will also work for other output formats such as HTML.
You can set the section numbering depth with the metavariable
secnumdepth. For example, to number chapters and sections (or sections
and subsections, depending on the top level section type), you can add the
secnumdepth: 2
This will only affect LaTeX and PDF output, though, and not other
output formats.
Alternatively, you can leave the section numbering entirely up to the
numberSections

59

Chapter 7

Cross-referencing

to true and set the section depth you want to be numbered with the
sectionsDepth
chapters and sections, but not subsections, numbered (assuming the top
level headers are chapters; otherwise you get sections and subsection
numberSections: true
sectionsDepth: 2
This will insert chapter and section numbers at the desired depth
and let you cross-reference sections in HTML and EPUB format, but
unfortunately the cross-referencing does not work in LaTeX and PDF. Here,
you only get the section numbers but not the cross-references inserted.
Neither of the two choices for section numbering is ideal for both PDF
and EPUB output. Using
--number-sections
will insert section numbers in both output formats, but you can only
control the numbering depth in PDF output. Using
numberSections
will insert section numbers to the desired depth in both output formats,
but you can’t insert references to them in PDF output. You can’t use both
--number-sections
and
numberSections
either since both the Pandoc filter and LaTeX will insert section numbers,
and you end up with two of them in each header.
60

Chapter 7

Cross-referencing

One solution I use for this is to call Pandoc with different options when
generating EPUB and PDF. For EPUB output, I use
--filter pandoc-crossref ...
For PDF output, I use
pandoc --number-sections \
--filter pandoc-crossref ...
I set the numbering depth in my YAML header, using both options for
controlling that:
sectionsDepth: 2
secnumdepth: 2

Reference Prefixes
When you need to refer to a section, you use the syntax
[@sec:label]
When you reference a section this way, the filter will insert both the
section number and a default prefix, which is “sec.” for a single section and
“secs.” for multiple sections. You can refer to more than one section but
separating the labels by semicolons inside the square brackets:
[@sec:label1; @sec:label2]
For documents where you have both chapters and sections, this might
not be what you want. There you might want to use the prefix “Chapter”
for chapters and “Section” for sections. Unfortunately, you cannot make
prefixes that depend on the header depth, but you can disable the prefixes
by overriding them.

61

Chapter 7

Cross-referencing

You can either change the reference prefix on a per-reference basis or
globally through metadata. For referring to chapters as “Chapter” rather
than “sec.”—as in this example—the best solution is probably to set the
prefix explicitly when referring to a chapter, but we can see how both
approaches work.
To use a per-reference specific prefix, you need to insert the prefix
you want between the start square bracket and the label. So, to make
the prefix for the reference to a chapter be “Chapter,” we would write
[Chapter @sec:chapter].
To change the prefixes globally, we need to set a metadata variable.
The metadata variable that controls the section references prefix is
secPrefix. If we set it to the empty string, we get rid of the prefixes.
secPrefix: ""
You can then manually insert the prefixes you want in the Markdown text:
See Chapter[@sec:chapter]
and Section[@sec:section].
Notice the lack of spaces between prefix and references here. This
is needed for PDF output; the LaTeX document that Pandoc generates
for the references contain a hard space, so if we put a space between the
prefix and reference, the PDF document will have too much space in the
generated text. For HMTL and EPUB, it doesn’t matter.
Completely disabling a prefix can be done on a per-reference basis
as well. Just add a “-” between the start bracket and the label. If you write
[-@sec:chapter], you only get the chapter number and not the prefix.
You rarely need to set the default prefix to the empty string explicitly. But
using that as an example gave me an excuse to introduce the variable.
You can set the secPrefix metadata to a list. The first element is
used for single references and the second for plural. So, to use “Sect.” as

62

Chapter 7

Cross-referencing

the prefix for a reference to a single section, and “Sects.” as the prefix for
multiple sections, we could specify this metadata:
secPrefix: ["Sect.", "Sects."]
The prefix list can have any length, and the number of references is
used to select a prefix. So, if you want a special prefix when you refer to
three sections, you can add a third element to the list. When you have
more references than prefixes, you get the last element in the list. Thus, if
you specify two elements in the list, the first is used for singular references
and the second for multiple references.
You might want to use lowercase “sect.” when you refer to a section in
the middle of a sentence but “Sect.” at the beginning of sentences. With
pandoc-crossref it is simple to switch between uppercase and lowercase
label prefixes. If you insert a label that starts with an uppercase, your prefix
will be in uppercase as well. Thus, if you write [@Sec:label], the default
prefix will be “Sec.”; if you write [@sec:label], the default prefix will be
“sec.”. The same goes for references to figures, tables, equations, and so on.

Referencing Figures, Tables, and Equations
To reference figures, you use the same syntax as for sections, except for
where you define figure labels and the prefix of the labels. To define a label
for a figure, you must give it the prefix #fig: and place the label right after
the markup for inserting the figure, so using the syntax
You cannot put a space between the figure insertion and the label
definition. You refer to figure labels as you would with references to
sections.

63

Chapter 7

Cross-referencing

caption:
a   b   c
--- --- --1   2   3
4   5   6
: Caption {#tbl:label}
For tables you must have a space between the caption and the label.
For display-style math, math that stands on a line of its own and is
written with two dollar signs, you can add labels if they begin with #eq:
and are put on the same line as the math with a space between the label
and the terminating double dollar signs:
$$f(x) = x^2 + a x$$ {#eq:label}
You can change the default prefix for figures, tables, and equations,
as you can for sections, with the metadata figPrefix, tblPrefix, and
eqnPrefix, respectively.
For more details on how to use the cross-reference filter, I will refer to
its online manual.4

B
 ibliographies
If your text requires citations and a bibliography, you can enable the filter
pandoc-citeproc by either running Pandoc with the
--bibliography
option or using
--filter pandoc-citeproc

4

64

Chapter 7

Cross-referencing

If you use both pandoc-crossref and pandoc-citeproc filters, you
must always use pandoc-crossref first
pandoc --filter pandoc-crossref \
--filter pandoc-citeproc ...
The two filters use similar kinds of citation syntax, and this means
that the order in which you run the filters matter. The citeproc filter gets
confused if it sees cross-reference labels. The same does not happen if you
run the cross-reference filter first; it will leave the citation codes alone so
they can be handled by the citation filter.
With the --bibliography option, you need to specify the file that
--filter pandoc-citeproc
--    bibliography: citations.bib
--The pandoc-citeproc filter can read bibliographies in various file
formats and will pick the format based on the file suffix. With .bib files it
will use BibTeX. For EndNote you would use .enl and for ISI .wos. Check
the online documentation5 for a complete list.
To control the format used for citations and the bibliography, you can
specify a CSL6 file with the metadata variable csl or the Pandoc option
--csl. CSL files for most journal styles can be downloaded from GitHub.7
For example, if “smith12” is a key in your bibliography, you can insert a
citation using [@smith12]. You need to include @ even though it isn’t part
h ttps://tinyurl.com/yyx6j3aa
http://citationstyles.org
7
https://tinyurl.com/ac8f8eg
5
6

65

Chapter 7

Cross-referencing

of the reference key; the filter (and Pandoc) uses this to recognize citations.
You can cite more than one reference by separating the references with
semicolons: [@smith12; @smith14].
Depending on the citation style, the inserted reference might contain
authors in the text, and you can disable it with a minus before the
reference: [-@smith12]. The same effect is achieved by leaving out the
square brackets and write @smith12.
More generally, you can insert text in the citations to add, for example,
page information or other comments, such as [see @smith12, chap1;
also @smith14, chap 12]. If you leave out the square brackets to get an
square brackets after the reference: see @smith12 [chapter 11].
The bibliography will be put at the end of your document. If you want
to give the bibliography a section header, you should end your Markdown
document with the header for the bibliography.

Exercises
Reference Sections
Write three sections. In two and three, refer back to one and two, respectively.

Figures, Tables, and Equations
Write a document with each of a figure, a table, and an equation. Make
references to each.

Bibliographies
If you have a bibliography, then make a document that cites the elements in it.
66

CHAPTER 8

If you go back and look at the standalone HTML document we looked at in
# This is a test document
Here is some text in the document.
* This is a list
* With two items
We compiled it like this
pandoc --standalone -o output.html input.md
You should get the warning
[WARNING] This document format requires a nonempty
<title> element.
Please specify either 'title' or 'pagetitle' in
e.g. by using --metadata pagetitle="..." on the
command line.
Falling back to 'input'
and the title in your document will then, just as the warning says,
look like this:
<title>input</title>
T. Mailund, Introducing Markdown and Pandoc,
https://doi.org/10.1007/978-1-4842-5149-2_8

67

Chapter 8

Pandoc inserted a title to your document, but it is set to a default value,
input, because we didn’t specify it. Try running this command instead:
--standalone -o output.html input.md
If you now read the output.html file, you will see that Pandoc has
inserted “My Title” between the title tags and inserted a level-one header
that says “My Title”.
When Pandoc generates a standalone document, it uses metadata such
as title and author(s) to fill in some information. This data is usually not
specified in the Markdown input—there aren’t any Markdown annotations
option or using YAML (see the following text).
Strictly speaking, there are two types of variables that are used when
specified with --variable. The difference between them is that metadata
can be seen and processed by Pandoc and Pandoc filters—scripts that
process your input before it is formatted for the output—while variables
are used in templates. If you set a variable using the --metadata tag, or in
a metadata header, the variable will also be available to templates, so you
can usually stick to metadata. The output isn’t exactly the same since filters
might do something with metadata that they won’t do with variables, but it
is easier to stick with one kind of options. So unless you have good reasons

There are potentially many values you want to specify as metadata, so
you don’t want to rely on command line options for all of those. Luckily,
another markup language called YAML (Yet Another Markup Language).
68

Chapter 8

YAML is a different kind of markup language than Markdown. It is not
intended for marking up a text but for providing structured data to tools.
to provide Pandoc with theinformation. I usually put my metadata in a
separate file instead and give that as the first input file when I run Pandoc.
Since Pandoc concatenates the input files you give it, this is equivalent
to putting the metadata at the top of the document, but it does give me
the option of using different headers when I produce output in different
formats and I can easily format different Markdown files with the same
A YAML header starts with three hyphens --- on a line of their own
and is terminated with another three hyphens. Inside the header, you
can put key-value information. The keys are followed by a colon, and the
values follow the colon. The header I use for this book looks like this:
--title:
"My Markdown and Pandoc book"
author:
- Thomas Mailund
year: 2019
--It sets three values, the title, the author, and the year I am writing the
book, which is all that I need for this book. I didn’t need to put the title
in quotes. I could write it as it is, the same way I write my name in the
author’s field. However, if a title, or any value in general, contains a colon,
you do need to put the value in quotes. Here, I use the quotes to show that
as an example.
You will notice that for the author: field I have a hyphen before my
name. I didn’t have to put that there either, but I did to show you a list.
When you want a key to refer to a sequence of values, for example, if

69

Chapter 8

you have more than one author on a document, you use hyphens before
each element in the list. Here, I make author refer to a list of length one.
The result is the same as if I hadn’t put my name in a list, but if I had a
coauthor, we would need the list syntax.
I have this header in a file called header.yml, and I can compile the
book into a PDF file with the command
The actual command line is more complex (see the Makefile in
Chapter 5), but this command would suffice to generate a book.
The YAML language is essentially a way of mapping keys to values.
In the preceding header, you have three keys: title, author, and year.
A key can map to a single scalar value. title and year do that. They can
also map to a list, as author does. Keys can also map to nested key-value
mappings. Consider this:
author:
- name: Thomas Mailund
affiliation: Unseen University
- name: Karsken Baelg
affiliation: Brakebills University
Here author is a list—you can see this because you have dashes before
each author. Each author is a nested mapping; they have two keys, name
and affiliation. That it is another mapping is because they have keys
followed by a colon and then values to the right of this. In short, scalars
are keys followed by a single value, lists are keys followed by a sequence of
items separated by hyphens, and nested maps are nested key-value maps.
For lists and maps, there is a more concise notation. For a list you can put
its values in square brackets and comma-separate them:
author_names: ["Thomas Mailund", "Karsken Baelg"]

70

Chapter 8

For maps you can use curly brackets instead
author:
- { name: "Thomas Mailund",
affiliation: "Unseen University" }
- { name: "Karsken Baelg",
affiliation: "Brakebills University" }
Here, the items in the list have the same structure. They need not have
this; it is easier to write code to process it when they do, though.
If you have a long text, you can break it into several lines in the YAML
file using either | or >
abstract: |
This is a very long abstract and
it is probably the best paper ever.
We are sure that you will all agree.
The difference between the two is that | will preserve linebreaks, while
> will remove new lines and replace them with space. You can continue the
text in these blocks as long as you want to, as long as you indent each line.
You can write arbitrarily complex YAML, but Pandoc will only use the
metadata that it knows how to process. Which variables are interpreted by
Pandoc depends on the output format and the template you that use (see
Chapter 9). Check the Pandoc manual at https://tinyurl.com/yyxgole5
for details on the default templates, and see Chapter 9 for how to use

71

CHAPTER 9

Using Templates
When Pandoc creates a standalone document, it uses a template for the
output. A template is essentially a document with some placeholder
inserted. Which metadata will be used in a template depends on the
output format; you can get a full list of variables for your output in the
Pandoc manual.1 Pandoc automatically sets some metadata, described in
Unless you specify another template explicitly, Pandoc will use a
default for the output format. You can get Pandoc to show you the template
it uses for a specific output by running the
pandoc -D <format>
command, for example, to see what it will use if you generate a PDF file—
which it does by generating a LaTeX document and then compiling it—you
can write
pandoc -D latex
You can also get a full list of default templates and what they look like
at https://github.com/jgm/pandoc-templates.
If you don’t know LaTeX, the template you get by running
pandoc -D latex
http://pandoc.org/MANUAL.html#templates

1

T. Mailund, Introducing Markdown and Pandoc,
https://doi.org/10.1007/978-1-4842-5149-2_9

73

Chapter 9

Using Templates

might not make much sense, so let us look at
pandoc -D html
instead. The output is rather long, and I won’t replicate it all here but
highlight a few parts of it.
Remember the title we discussed in Chapter 8. It was empty before we
provided metadata for the title. Let us see what it looks like in the template.
There you will find a line that looks like this:
<title>
$if(title-prefix)$
$title-prefix$   $endif$
$pagetitle$
</title>
The stuff in dollar signs specifies placeholders and code for how the
template should be processed. Inside the title tags in the HTML template,
you have two metadata variables that can be inserted, title-prefix and
pagetitle. The title prefix will only be inserted if it exists; that is what the
$if(title-prefix)$ code checks. Strictly speaking, pagetitle will also
only be inserted if it exists. Otherwise, we get an empty string. But because
the title prefix should be followed by a dash, there is an explicit test to see if
anything should be inserted.
We never provided metadata for title-prefix and pagetitle, so it is
hard to see how they relate to the title metadata we provided. We could
have provided those two explicitly, but Pandoc creates them based on our
title. It directly uses title variable elsewhere in the template, where the
template contains:
<h1 class="title">$title$</h1>

74

Chapter 9

Using Templates

you should rely on any