Introducing Markdown and Pandoc Using Markup Language and Document Converter 1st Edition Thomas Mailund instant download
Introducing Markdown and Pandoc Using Markup Language and Document Converter 1st Edition Thomas Mailund instant download
https://textbookfull.com/product/introducing-markdown-and-pandoc-
using-markup-language-and-document-converter-1st-edition-thomas-
mailund/
https://textbookfull.com/product/introducing-the-
mysql-8-document-store-1st-edition-charles-bell/
https://textbookfull.com/product/introducing-the-
mysql-8-document-store-charles-bell/
https://textbookfull.com/product/string-algorithms-in-c-
efficient-text-representation-and-search-1st-edition-thomas-
mailund/
https://textbookfull.com/product/domain-specific-languages-in-r-
advanced-statistical-programming-1st-edition-thomas-mailund/
Domain Specific Languages in R Advanced Statistical
Programming 1st Edition Thomas Mailund
https://textbookfull.com/product/domain-specific-languages-in-r-
advanced-statistical-programming-1st-edition-thomas-mailund-2/
https://textbookfull.com/product/metaprogramming-in-r-advanced-
statistical-programming-for-data-science-analysis-and-
finance-1st-edition-thomas-mailund/
https://textbookfull.com/product/the-joys-of-hashing-hash-table-
programming-with-c-1st-edition-thomas-mailund/
https://textbookfull.com/product/functional-programming-in-r-
advanced-statistical-programming-for-data-science-analysis-and-
finance-1st-edition-thomas-mailund/
https://textbookfull.com/product/beginning-data-science-in-r-
data-analysis-visualization-and-modelling-for-the-data-
scientist-1st-edition-thomas-mailund/
Thomas Mailund
If you are used to WYSIWYG editors such as Microsoft Word, you might
reasonably ask why you should use Markdown files. You can write your
document and format them any way you like, and you can export your
document to different file formats if you wish. For short documents
that you only need to format once and to one file format, you do not
need Markdown. I will argue that Markdown is still an excellent choice
for such documents, but it is for more advanced applications where it
really shines.
For applications that are just as easy to handle with a WYSIWYG
editor, plain text can be a better choice in situations where you need to
share documents with others. A de facto file format for this is Word
files, but not everyone has Word. I don’t. I can import Word files into
Pages, which I have, and export to Word, but I don’t know what that
does to the formatting. Everyone has an editor that can work on plain
files, and with a plain text file, you know exactly what you are editing. If
the text and the formatting are separated, then someone with more
artistic skills can handle the formatting while I can write the text. One
argument for Word might be tracking of changes. This is an important
feature, but with plain text files, you can put them under real version
control, for example, GitHub, and that is superior to version tracking.
If you need your document in different formats, for example, you
might need to include your text in a printed progress report and also
have it on a web site, then you can export the document to as many file
formats as you need. If you need different typography for the different
file formats, you might have to do substantial manual work. You might
need to change all the document styles by hand, and in the numerous
occasions where you need to make changes to your text, you need to
change the styles for each file format more than once. If you separate
style and text, you avoid this problem altogether.
Using a markup language to annotate your text makes it easier for
you to distinguish between the semantic structure of a document and
how it is formatted. In the Markdown document, you markup where
headers and lists are, for example, but not how these should be
formatted in the final output. The formatting styles are held in different
files and you can easily transform your Markdown input into all the
output file formats and styles you need. Furthermore, someone else
can work on the style specification while you concentrate on the text.
Your Markdown doesn’t have to be in a single file either. You can split it
into as many as you want, and then different authors can work on
separate pieces of the text without worrying about how to merge files
afterward. With version control, you can even work on the same file in
parallel up to a point.
Figure 2-1 You can translate the text in multiple documents, or multiple chapters
that should be merged into a single document. You combine these with templates for
formatting the documents, and using Pandoc you can combine it all to produce the
documents you want.
Explicitly representing the semantic elements in the text, rather
than implicitly through how the text is formatted, is also essential if
you want to automatically make a table of contents or lists of figures
and tables. If all sections are marked up explicitly as sections, with
headers at different section levels, any tool can scan your document
and identify these. If the tools had to guess at the semantic meaning of
text elements, based on how the text was formatted, this would be a
much harder task.
Using WYSIWYG word processors doesn’t prevent you from
structuring your documents as semantic units—they usually support
this—but having an explicit markup language makes it much easier to
enforce.
Preprocessing Documents
If your documents are in plain text, you also get a lot of options for how
to process your document before you format it into a final output.
There are a large number of tools that will work well with plain text and
let you preprocess your documents.
Preprocessing documents often require a few programming skills,
so it might not be the first thing you want to worry about if you are
only interested in writing text, but since the option is there, you can
write your text without worrying about processing it initially, and add
such steps later.
I write a lot about R programming, and in those books, I have a lot of
code examples. Here, I use another preprocessor, one that lets me
evaluate the code when processing the documents so I know that all
the code examples work and so I can get the output of running code
inserted into the documents automatically before I create the output
formats.
Preprocessing your documents adds some complications to how
you format your text, but the complexities are only there when you
need them. If you do not need a preprocessor, then you can ignore that
they exist altogether. If you do need preprocessing, then read Chapter
10.
Why Markdown?
There are many different markup languages you can use. HTML
(hypertext markup language) is used for web pages. TeX and LaTeX are
used for many kinds of text documents but are especially powerful for
typesetting mathematics. Markdown is what we do on in this book.
What makes Markdown particularly pleasant to work with is its
simplicity. In HTML, for example, you need to structure your text using
tags that enclose every paragraph, every header, every list, and so on.
When you edit an HTML document, it is hard to separate the
annotations from just the text you want to write. LaTeX has the same
problem. The annotation of the text can be hard to ignore when you
want to focus on writing.
Worse, if you write your documents in HTML or LaTeX, much of the
text is markup codes that specify the formatting. How much, of course,
depends on your document, but any markup instructions you make can
make the text difficult to read.
Consider this Markdown document:
This is a paragraph
* an unnumbered
* list
1. and a numbered
2. list that is
3. three items long
I hope you will agree that the markups here are minimal and that
they do not get in the way of reading or writing the text.
For comparison, the HTML version of the same text looks like this:
<h1>This is a level one header</h1>
<p>This is a paragraph</p>
<h2>This is a level two header</h2>
<p>Here is a paragraph that is followed by</p>
<ul>
<li>an unnumbered</li>
<li>list</li>
</ul>
<ol type="1">
<li>and a numbered</li>
<li>list that is</li>
<li>three items long</li>
</ol>
It is not terribly complicated, and after looking at it a bit, you can
certainly follow the structure of a document. It is far from as clean as
the Markdown file.
The LaTeX version is slightly easier to read than the HTML file, but
there are still several formatting instructions that get in the way of just
writing.
\begin{itemize}
\item an unnumbered
\item list
\end{itemize}
\begin{enumerate}
\item and a numbered
\item list that is
\item three items long
\end{enumerate}
Markdown is designed so you can annotate your text with semantic
information with little annotation clutter. It is designed such that
reading the input text is almost as easy as reading the formatted text.
With Markdown you don’t have quite the same power to control your
formatting as you do in a language like LaTeX, but the simplicity of
Markdown more than makes up for it.
Why Pandoc?
Since Markdown is just a language for adding structure to a text, it is
not tied to any particular tool. You can use any Markdown-aware
software when you want to process your documents. Many blogging
platforms will let you write your text in Markdown and automatically
format it for you. Translating Markdown into HTML was, after all, one
of the primary motivations for the language. Now, many text editors
also support Markdown and will support formatting in Markdown and
exporting to various file formats, usually with various formatting and
style choices determining what your output files will look like.
If your editor can export to different file formats and in different
styles, then that is obviously the easiest way for you to export your
Markdown text. With Pandoc, however, you have a lot of power over
how your documents should be processed. Pandoc is vastly more
versatile than any Markdown-aware text editor that I am aware of.
If you want to create a simple document with no fluff, it is easy to do
so with Pandoc, but easier to do from inside your editor. Try using
Pandoc for simple cases though, so you get familiar with the tool. When
you get into serious writing, and you want full control of how your final
documents will look, then you need the power of Pandoc. The learning
curve can be steep, but if you are familiar with using Pandoc for simple
documents, then you have a foundation to build on when you explore
advanced features.
© Thomas Mailund 2019
T. Mailund, Introducing Markdown and Pandoc
https://doi.org/10.1007/978-1-4842-5149-2_3
3. Writing Markdown
Thomas Mailund1
If you have used plain text to write and share documents in the past,
then you are likely to be familiar with most Markdown markup
annotations already. Much of the syntax for Markdown is based on how
people have written plain text documents for years. This chapter
covers the basic Markdown annotations, which make up 99% of the
annotations you will use regularly. The notation I present in this
chapter is supported by all Markdown tools (as far as I am aware). The
next chapter covers notation that is not universally supported although
many tools do support the features there. All of them, of course, are
supported by Pandoc.
If you write plain text with no special markup commands, as listed
in the remainder of this chapter, then the result will be plain text in the
output as well. One or more lines of text becomes a paragraph. If you
need to start a new paragraph, then use two new lines, that is, separate
one paragraph from the next with a blank line.
Sections
At the highest level, a text document is composed of its sections.
Sections come at different levels. In a book, the top level might be
chapters, the second level sections within the chapters, and the third
level are subsections within the sections.
To make a new section, you give it a header. The headers start with
a hashtag. Using one hashtag gives you a level-one header, which will
be a chapter in a book or a section in a smaller document. Two
hashtags give you a level-two section, a section if the first level is
chapters or a subsection if the first level is section. The next level
sections have three hashtags, and so on.
# Header level 1
## Header level 2
### Header level 3
For the first two levels, you can alternatively underline the section
titles with = and -, respectively:
Any text you write following a header becomes the body of the
section.
By default the headers are numbered. You can change this using a
template (see Chapter 9) or you can disable numbering on selected
headers by putting “{-}” or “{.unnumbered}” after the header title :
Emphasis
We emphasize part of a text by putting it in italic or boldface. In
Markdown we use asterisks, ∗, to do this. To put a word in italic, we use
one asterisk, and to put it in boldface, we use two.
The preceding section, in Markdown, looks like this:
Lists
You have two kinds of lists : numbered and unnumbered . To create a
numbered list, you put a number, followed by a period, at the start of a
line and write the list item after it. For the next list item, you go to the
next line, add another number, followed by a dot, and write the next
item text. An example could look like this:
The actual numbers are ignored, so you can get the same result if
you wrote:
If you want your list items to span multiple lines, you need to indent
the lines following the number, like this :
2. Here is another one. Where this is also part of the list item.
Just add sufficient spaces to put the sub-items under the enclosing
item. The result will look like this:
This is a top-level list item
– Here is a sublist item
– Here is another
Now we are at the top level again.
When you indent, you need at least four spaces or a tab per level .
Block Quotes
Should you need to add a quote to your text, you put a “>” before the
quoted text.
So you can write:
Verbatim Text
Sometimes, you don’t want any formatting at all of a text; you want to
leave it verbatim as it is. When you want this, you can indent it with a
tab (or four spaces). You can write this:
Links
Markdown was initially written to make it easier to write content for
web pages. Consequently, it has built-in syntax for inserting hypertext
links . These will work both with links to web pages and for cross-
references within your text.
You have two options for specifying a link: you can put the
destination URL where you insert the link, or you can create a label and
map it to the URL so you can refer to the label when you insert a link. To
put the URL where you insert the link, you put the text you want to be
the link in square brackets and the destination URL for the link in
round parentheses right after. You would write a text like this:
This is fine for most cases, but if you have many links in a
paragraph, then the link annotations start interfering with how easy it
is to read the text. Instead, you can give the destinations a shorter
name and put the destination later in the text. To do this, you replace
the round parentheses with square brackets, like this:
Then, later in the text, you define what the link should point to like
this:
[blog]: http://www.mailund.dk
You use the same syntax to make hypertext links within your
document . The simplest way to create a link to a section is to leave out
the destination but put the name of the section in square brackets. A
link to this chapter would then be written like this :
This is a link to the [Writing Markdown]
chapter.
This, of course, will not work if you want the link to contain a
different text than the section name, or if you have several sections
with the same name. You can work around this by giving the section
headers explicit labels. These, you put in curly brackets after the
section header. You can assign a label to a header like this:
# My header {#header}
Images
To insert figures in your document, you use a syntax similar to
inserting links. The difference is that you need to put a bang, “!”, before
the link.
Typically, you will have the figures as local files and there you use
the path to the figure file, either relative to where you build your
document or as an absolute path.
Exercises
In the following text are a few exercises where you can test yourself on
the material covered previously. If you use an editor that can
immediately show you the result of a Markdown text, then test your
results there. Otherwise, put your answers aside until we have covered
how to format Markdown in Chapter 5.
Sections
Write a document with three level-two sections and with two level-
three sections inside each. Remember that the number of # determines
the section level. Make them both numbered and unnumbered.
Emphasis
Write this text in Markdown.
Lists
Take the three items
one item
two items
three items
and write them as a numbered and an unnumbered list.
Now, put
four items
five items
as a sublist under one item.
Block Quotes
Make the following text a block quote:
Links
Write a text and insert a link to a web page and to a section in your text.
Images
Find an image file and insert it into a text.
© Thomas Mailund 2019
T. Mailund, Introducing Markdown and Pandoc
https://doi.org/10.1007/978-1-4842-5149-2_4
Lists
Generally, the numbers you use when you write an ordered list are
ignored. They are used to indicate list items, but the actual numbering
does not matter. This makes it easier to insert a new item in the middle
of a list, which is a good thing, but sometimes you want to start a list at
a different number than one, and in that case, basic Markdown can’t
help you. With Pandoc, though, lists start with the number you give the
first item in a list. So you can start a list at number three like this:
Our website is not just a platform for buying books, but a bridge
connecting readers to the timeless values of culture and wisdom. With
an elegant, user-friendly interface and an intelligent search system,
we are committed to providing a quick and convenient shopping
experience. Additionally, our special promotions and home delivery
services ensure that you save time and fully enjoy the joy of reading.
textbookfull.com