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

PDF output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

.epub output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

Further Reading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

About me . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

2

Alchemy?

Figure 1: Alchemist - Joseph Wright

Alchemy!

Alchemy is an influential philosophical tradition whose practitioners have, from antiquity, claimedit 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

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 tostructurally 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

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

• 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. One1. Another Level3. And more

1. Two1. Something Else

1. One

1. Another Level2. And more

2. Two3. 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

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


7

Markdown Syntax - Simple Tables• More than one way to specify tables, varies by implementation• Simple tables

Right Left Center Default------- ------ ---------- -------

12 12 12 12123 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

Markdown Syntax - Code Samples• Original markdown indents code block with four spaces• Larger code blocks should use fenced code blocks

~~~~{.php}<?phpecho "Hello World. Today is";echo date(’Y-m-d H:i’);~~~~

<?phpecho "Hello World. Today is";echo date(’Y-m-d H:i’);

9

A simple markdown example.


The United States Men’s national team advanced from Group Gin 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 standingsare shown below.

Team W D L------- --- --- ---Germany 2 1 0USA 1 1 1Portugal 1 1 1Ghana 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

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 Cupheld in Brazil.</p><p>With a win against Ghana, a last minute tie against Brazil, the team secured 4points 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

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

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