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. Table of Contents 4 About the Author 8 About the Technical Reviewer 9 Chapter 1: The Beginner’s Guide to Markdown and Pandoc 10 Chapter 2: Why Use Markdown and Pandoc 13 Separating Semantics from Formatting 14 Preprocessing Documents 16 Why Markdown? 17 Why Pandoc? 19 Chapter 3: Writing Markdown 21 Sections 21 Emphasis 22 Lists 23 Block Quotes 25 Verbatim Text 26 Links 26 Images 28 Exercises 28 Sections 29 Emphasis 29 Lists 29 Block Quotes 29 Links 30 Images 30 Chapter 4: Pandoc Markdown Extensions 31 Lists 31 Tables 35 Smart Punctuation 40 Footnotes 41 Exercises 42 Lists 42 Tables 42 Footnotes 42 Chapter 5: Translating Documents 43 Formatting a Markdown Document with Pandoc 43 Frequently Useful Options 48 Sections and Chapters 48 Table of Contents 49 Image Extensions 49 Ebook Covers 50 Using Makefiles 50 Chapter 6: Math and Computer Programming Languages 54 Writing Math 54 Writing Code Blocks 57 Code Block Options 59 Syntax Highlighting Styles 61 Exercises 62 Code blocks 62 Code Block Options 62 Syntax Highlighting 62 Chapter 7: Cross-referencing 63 Referencing Sections 64 Reference Prefixes 67 Referencing Figures, Tables, and Equations 69 Bibliographies 70 Exercises 72 Reference Sections 72 Figures, Tables, and Equations 72 Bibliographies 72 Chapter 8: Metadata 73 YAML for metadata 74 Chapter 9: Using Templates 78 Writing Your Own Templates 82 Template Examples 83 Exercises 94 Chapter 10: Preprocessing 95 Examples 96 Including Files 96 Conditional Inclusion 98 Running Code 100 Exercises 102 Chapter 11: Filters 103 Exploring Panflute 108 Conditional Inclusion of Exercise Solutions 110 Conditional Inclusions Based on Format 116 Evaluating Code 119 Numbering Exercises 123 Exercises 134 Conditional Inclusion 134 Conditional on Output 134 Evaluating Code 135 Numbering Exercises 135 Chapter 12: Conclusions 136 Index 137 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, only how you can use it to write documents in Markdown. 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. You will: 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 Front Matter ....Pages i-ix The Beginner’s Guide to Markdown and Pandoc (Thomas Mailund)....Pages 1-3 Why Use Markdown and Pandoc (Thomas Mailund)....Pages 5-12 Writing Markdown (Thomas Mailund)....Pages 13-22 Pandoc Markdown Extensions (Thomas Mailund)....Pages 23-34 Translating Documents (Thomas Mailund)....Pages 35-45 Math and Computer Programming Languages (Thomas Mailund)....Pages 47-55 Cross-referencing (Thomas Mailund)....Pages 57-66 Metadata (Thomas Mailund)....Pages 67-71 Using Templates (Thomas Mailund)....Pages 73-89 Preprocessing (Thomas Mailund)....Pages 91-98 Filters (Thomas Mailund)....Pages 99-131 Conclusions (Thomas Mailund)....Pages 133-133 Back Matter ....Pages 135-139