Publishing alchemy with markdown and pandoc
Upcoming SlideShare
Loading in...5
×

Like this? Share it with your network

Share

Publishing alchemy with markdown and pandoc

  • 6,686 views
Uploaded on

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

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.

More in: Technology
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Be the first to comment
No Downloads

Views

Total Views
6,686
On Slideshare
6,676
From Embeds
10
Number of Embeds
2

Actions

Shares
Downloads
12
Comments
0
Likes
1

Embeds 10

https://twitter.com 7
http://www.slideee.com 3

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
    No notes for slide

Transcript

  • 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 ! ![Need Work](./images/jobless-cylon.jpg) 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. ![USSF Logo](./images/US_Soccer_logo.png) 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