Don't confine your content to a single output! Using markdown to write documents, coupled with the open-source pandoc tool, you can easily create a myriad of output format First, we'll learn about markdown syntax, and its different flavors. Then, we'll see how to use pandoc to generate HTML pages, eBooks, PDF documents, and even Word files.

1. Publishing Alchemy with Markdown and pandoc
Oscar Merida
July 22, 2014
Contents
Alchemy? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Alchemy! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Our Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
What can we do with them? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Genesis of Markdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Markdown Advantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Markdown Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Flavors of Markdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Markdown plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
Markdown Syntax - Headings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Markdown Syntax - Text Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Markdown Syntax - Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Markdown Syntax - Unordered Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Markdown Syntax - Ordered Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Markdown Syntax - Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Markdown Syntax - Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Markdown Syntax - Simple Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Markdown Syntax - Grid Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Markdown Syntax - Grid Tables, 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Markdown Syntax - Code Samples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
A simple markdown example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
A simple markdown example, rendered. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Example, As HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Pandoc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Pandoc extensions to markdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Structuring a large document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1

2. PDF output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
.epub output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Further Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
About me . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
2

3. Alchemy?
Figure 1: Alchemist - Joseph Wright
Alchemy!
Alchemy is an influential philosophical tradition whose practitioners have, from antiquity, claimed
it to be the precursor to profound powers.
Our Tools
• Markdown, a plain text format for writing.
• Pandoc, a command line tool for converting from one markup to another.
What can we do with them?
• Prepare technical and other documentation for projects
• Write articles for a blog
• Publish a book
• Create slides for a presentation
3

4. Genesis of Markdown
Created in 2004 by John Gruber and contributions from Aaron Swartz
“to write using an easy-to-read, easy-to-write plain text format, and optionally convert it to
structurally valid XHTML (or HTML)”
See the release: http://daringfireball.net/projects/markdown/
Markdown Advantages
• Plain text, easier to focus on writing
• Files are easy to version with git, svn, etc
• Much more readable than raw HTML
• Editable in any text editor, and. . .
Markdown Editors
• MarkdownPad for Windows
• Mou, iA Writer on
• ReText for Linux
• Online markdown editors like dillinger.io
• and many others for iOs, Android, etc
Flavors of Markdown
Unfortunately there is not a clearly defined Markdown standard
• Github markdown
– URL autolinking, strikethrough, fenced code blocks, syntax highlighting
• MultiMarkdown
– footnotes, tables, citations, captions
• Markdown Extra
– fenced code blocks, tables, footnotes
• Pandoc Markdown
– tables, syntax highlighting, inline footnotes
Markdown plugins
• For Wordpress, WP-Markdown
• For Drupal, Markdown filter
• PHP, PHP Markdown Extra
• As a service StackEdit
• Javascript Editor EpicEditor
4

5. Markdown Syntax - Headings
• One or more #
• Provide document structure
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
<h1>Heading 1</h1>
<h2>Heading 2</h2>
<h3>Heading 3</h3>
<h4>Heading 4</h4>
<h5>Heading 5</h5>
Markdown Syntax - Text Blocks
• Paragraphs are separated by a new line.
• Block Quotes begin with a >.
I should have used lorem ipsum here as an example of text
> And here is another paragraph
I should have used lorem ipsum here as an example of text
And here is another paragraph
Markdown Syntax - Formatting
*italic* _italic_
**bold**__bold__
‘monospace‘
italic italic
bold bold
monospace
Markdown Syntax - Unordered Lists
• Bullets can be +, -, *
• Nested lists are indented by 4 spaces.
- One
* Sub One
- Two
- Three
5

6. • One
– Sub One
• Two
• Three
Markdown Syntax - Ordered Lists
• Numbered lists use numbers followed by a period.
• Nested lists are indented by 4 spaces.
1. One
1. Another Level
3. And more
1. Two
1. Something Else
1. One
1. Another Level
2. And more
2. Two
3. Something Else
Markdown Syntax - Links
• Link text is enclosed with square brackets [].
• Alternatively, links in angled brackets <> will show the URL
• URL in Parentheses,
– can use absolute, relative paths too
Read [my blog](http://bytesinthemargin.com/)
<http://bytesinthemargin.com>
Read my blog
http://bytesinthemargin.com
6

7. Markdown Syntax - Images
• Same format as URL, but starts with !
7

8. Markdown Syntax - Simple Tables
• More than one way to specify tables, varies by implementation
• Simple tables
Right Left Center Default
------- ------ ---------- -------
12 12 12 12
123 123 123 123
1 1 1 1
Right Left Center Default
12 12 12 12
123 123 123 123
1 1 1 1
Markdown Syntax - Grid Tables
+---------------+---------------+--------------------+
| Fruit | Price | Advantages |
+===============+===============+====================+
| Bananas | $1.34 | - built-in wrapper |
| | | - bright color |
+---------------+---------------+--------------------+
| Oranges | $2.10 | - cures scurvy |
| | | - tasty |
+---------------+---------------+--------------------+
Markdown Syntax - Grid Tables, 2
Fruit Price Advantages
Bananas $1.34 • built-in wrapper
• bright color
Oranges $2.10 • cures scurvy
• tasty
8

9. Markdown Syntax - Code Samples
• Original markdown indents code block with four spaces
• Larger code blocks should use fenced code blocks
~~~~{.php}
<?php
echo "Hello World. Today is";
echo date(’Y-m-d H:i’);
~~~~
<?php
echo "Hello World. Today is";
echo date(’Y-m-d H:i’);
9

10. A simple markdown example.
The United States Men’s national team advanced from Group G
in the 2014 World Cup held in Brazil.
With a win against Ghana, a last minute tie against Brazil,
the team secured 4 points and second place. Final standings
are shown below.
Team W D L
------- --- --- ---
Germany 2 1 0
USA 1 1 1
Portugal 1 1 1
Ghana 0 1 2
Source: [Wikipedia](https://en.wikipedia.org/wiki/2014_FIFA_World_Cup#Group_G)
A simple markdown example, rendered.
Figure 2: USSF Logo
The United States Men’s national team advanced from Group G in the 2014 World Cup held in Brazil.
With a win against Ghana, a last minute tie against Brazil, the team secured 4 points and second place.
Final standings are shown below.
Team W D L
Germany 2 1 0
USA 1 1 1
Portugal 1 1 1
Ghana 0 1 2
Source: Wikipedia
10

11. Example, As HTML
<h1>A simple markdown example, rendered.</h1>
<div class="figure">
<img src="./images/US_Soccer_logo.png" alt="USSF Logo"><p class="caption">USSF Logo</p>
</div>
<p>The United States Men’s national team advanced from Group G in the 2014 World Cup
held in Brazil.</p>
<p>With a win against Ghana, a last minute tie against Brazil, the team secured 4
points and second place. Final standings are shown below.</p>
<table>
<thead>
<tr class="header">
<th align="left">Team</th>
<th align="left">W</th>
<th align="left">D</th>
<th align="left">L</th>
</tr>
</thead>
<tbody>
<tr class="odd">
<td align="left">Germany</td>
<td align="left">2</td>
<td align="left">1</td>
<td align="left">0</td>
</tr>
<tr class="even">
<td align="left">USA</td>
<td align="left">1</td>
<td align="left">1</td>
<td align="left">1</td>
</tr>
<tr class="odd">
<td align="left">Portugal</td>
<td align="left">1</td>
<td align="left">1</td>
<td align="left">1</td>
</tr>
<tr class="even">
<td align="left">Ghana</td>
<td align="left">0</td>
<td align="left">1</td>
<td align="left">2</td>
</tr>
</tbody>
</table>
<p>Source: <a href="https://en.wikipedia.org/wiki/2014_FIFA_World_Cup#Group_G">Wikipedia</a></p>
11

12. Pandoc
• Written in Haskell
• Converts markup in one format to another
• From
– Markdown
– HTML
– LaText, and more
• To
– PDF
– Latex,
– EPUP, and more
• Read the Instructions for Installing Pandoc
– Windows, Mac OS X, Linux, BSD
Pandoc extensions to markdown
Thus, while pandoc allows the embedding of raw HTML, it discourages it, and provides other,
non-HTMLish ways of representing important document elements like definition lists, tables,
mathematics, and footnotes.
• Fancier lists
– Uppercase & lowercase letters, or Roman numerals
• Definition lists
• Inline footnotes
• Built in syntax highlighting
Read the Pandoc Documentation for details.
Structuring a large document
What if you’re writing a book, or long report? What if you have multiple contributors?
• Break up document into multiple files.
– One chapter per file
– Use a naming convention so that listing the files will put them in sequence
∗ 001-introduction.md
∗ chapter-01.md
• Put figures & Images in an images folder
• Use Git or Subversion to commit your changes, update to get other’s changes.
• Use a build script to execute pandoc
12

13. PDF output
• Requires a LaTeX engine
• --toc --toc-depth=N adds a Table of Contents
• “ to use raw tex commands
• Use pagebreak in your markdown to control Page Breaks
Convert markdown to pdf:
pandoc -s --toc --toc-depth=2 -o alchemy-markdown-pandoc.pdf slides.md
See this presentation a PDF
.epub output
• epub is a free & open e-book standard that uses HTML & CSS.
• Need an xml file for epub metadata.
<dc:title>Publishing Alchemy with Markdown and pandoc</dc:title>
<dc:language>en-US</dc:language>
<dc:creator opf:file-as="Merida, Oscar" opf:role="aut">Oscar Merida</dc:creator>
<dc:date opf:event="publication">2014-07-29</dc:date>
<dc:rights>Copyright c 2014 by Oscar Merida</dc:rights>
Convert markdown to epub
pandoc -s --toc --toc-depth=2 -o alchemy-markdown-pandoc.epub
--epub-cover-image=images/cover.jpg
--epub-metadata=book.xml slides.md
See this presentation an epub
Further Reading
• PuppetLabs: How We Automated Our Ebook Builds With Pandoc and KindleGen
• Convert from Word to markdown
• A Markdown Epub Builder
• Convert epub to MOBI with KindleGen
• S5 Html based Slide Shows
• Pandoc and LaTeX
About me
• PHP Developer since PHP3 day
• Drupal since 4.x
• php[architect] monthly magazine
– always looking for contributors
– we do books & training too!
• Follow me @omerida
• php[world] this November http://world.phparch.com
13