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.
Writing 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.
For HTML and EPUB, you have different options for how the output should handle math. I usually use either MathML
or MathJax
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,mathrm{d}x$ looks like
. You write display mode math between double dollar signs, so this
$$sum_{j=1}^N frac{1}{j^2}$$
Pandoc supports a large subset of math you can write in LaTeX. For example, here is a more complex equation:
The LaTeX
code
looks like this:
$$
d(i,j) = egin{cases}
,i & j = 0 \
,j & i = 0 \
,minegin{cases}
d(i-1,j-1) + mathrm{1}(i
eq 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.
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
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.
```
for (int i = 0; i < n; i++) {
printf("%d
", 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
", 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
", i);
}
```
The result will look like this:
for (int i = 0; i < n; i++) {
printf("%d
", i);
}
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)
```
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)
```
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.
In HTML output, all the options that start with a
. will be added to the 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
must start with a dot, and all options that take an argument
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
ewcommand 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 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.
