In our previous post we learned how to write and generate our study note and covered many of the Pandoc and Markdown basics. In this post we will learn additional features of the Markdown markup language, as well as a few additional markups that are only available in the extended-Markdown language, which is used by Pandoc.

Confused? Let me explain.

Markdown vs Pandoc Markdown

Markdown is a markup language with a limited set of formatting options. This is intentional:

> A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. – John Gruber

A Markdown file is pretty straightforward to read, whether it is in a text editor or as the README.md file on a GitHub page.

Pandoc understands a slightly extended version of Markdown. As indicated by its author:

> [The above] principle has guided pandoc’s decisions in finding syntax for tables, footnotes, and other extensions. > > There is, however, one respect in which pandoc’s aims are different from the original aims of Markdown. Whereas Markdown was originally designed with HTML generation in mind, pandoc is designed for multiple output formats. 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. – John MacFarlane

Thus, the Pandoc version of Markdown is somewhat easier for beginners as it avoids the use of HTML, and is much more powerful because it can be converted to dozens of other formats.

With that out of the way, let’s learn some additional tricks that might come in handy writing the rest of our study note.

Emphasis and other in-line markups

Bold. To make text bold, simply surround it by two asterisks. For example, **this is bold** will be rendered as this is bold.

Italic. To make text italic, use only one asterisk on either side. For example, *this is italic* will be rendered as this is italic.

Strikeout. To strike out text, surround it by two tildas. For example, ~~This text will be struckout~~ will be rendered as this text will be struckout

Superscript. To make something superscript, surround it by two carrats. For example, a^2+5^ will have the 2+5 in superscript (not rendered properly on this WordPress website).

Subscript. The same trick can be used for subscript, except that the text should be surrounded by single tildas: X~treatment~ would have the word treatment in subscript.

Verbatim. To have something appear without applying the markup, or to have something appear like commands, code or computer instructions, simply surround the text by backticks like this `backticks`. This will be rendered as backticks.

Lists

Lists are a great way to represent information. A few types are available to us in Markdown.

Bullet list

* First item in my list
* Second item in my list
    * Sub-item to the second item
* Third item to my list
  
  A second paragraph to my list item
* Fourth item to my list

Numbered list

1) First item in my list
2) Second item in my list
    1) Sub-item to the second item
3) Third item to my list
  
  A second paragraph to my list item
4) Fourth item to my list

Fancy list (Pandoc Markdown only)

This one is a great option if you might add list items and change the order of the items. Pandoc will number the list when it generates the output file.

#. First item in my list
#. Second item in my list
    #. Sub-item to the second item 
#. Third item to my list

   A second paragraph to my list item
#. Fourth item to my list

Task list (Pandoc Markdown only)

A simple way to add tick boxes to our document

- [x] Draft ethics application
- [ ] Finalise experimental set-up
- [ ] Pilot experiment
- [ ] Recruit first participant

Definition list (Pandoc Markdown only)

Scientist

: Curious person would is also curious

Academic

: Curious person

    This type of person may also be curious, but this trait is accompanied by other key traits, such
    as a love for administrative meetings, large teaching loads and inadequate support from their 
    institution

Tables

There are several ways to make Tables in the Pandoc flavour of Markdown. Below we see the two simplest and most commonly used, the second one allowing for multiple lines in the header. In these tables, where the text lines up with respect to the dashed lines determines whether the text will be centered, left aligned or right aligned. A Table title can be also specified.

subject    arm length   leg length    foot length
-------   ------------  -----------  ------------
sub01		40	        80	       30
sub02		44	        79	       36
sub03		42	        85  	       24

Table: This is a useful table


-------------------------------------------------
subject    arm length   leg length    foot length
centered    centered     left align   right align
-------   ------------  -----------  ------------
sub01	      40        80                     30

sub02	      44        79                     36

sub03	      42        85                     24
-------------------------------------------------

Footnotes

These are available in the Pandoc flavour of Markdown. One way to write footnotes is to include a reference to the footnote in the text and then define the footnote at the end of our document.

Here is a footnote reference,[^1] and another.[^2]

[^1]: Here is the footnote.
[^2]: Here's one with multiple blocks.

Text blocks

There are various styles of text blocks in Markdown, and the Pandoc flavour of Markdown.

Verbatim

If we want to write text and not have formatting applied to it, we can simply indent the text. This is how the various blocks of Markdown have been included in this post.

For example, the above text showing the footnote appears as following in my text editor:

Block Quotations

These can be included in our text by starting the line with the greater-than symbol >

For example:

Blah blah blah...

	> This is a quote from a wise sage.
	> 
	> She said "You don't go into science to feel good about yourself". 

Blah blah blah...

Will be rendered as:

Computer code

As mentioned in our previous post, we can include computer code to our Pandoc flavoured Markdown file.

For example:

from random import random

def grant_success(years_in_research, grant_success_rate):
    return random.random()

years_in_research = 12
grant_success_rate = 0.1

grant_success(years_in_research, grant_success_rate)

will be rendered as:

Horizontal line

A horizontal line, to separate two sections of test, can be added by including four or more dashes.

For example:

----

will be rendered like the line separating these two sections of text:

Summary

Markdown is quite simple. But if you need a refresher, there are lots of online tutorials and cheat sheets. Similarly, the Pandoc Manual gives a good overview of its flavour of Markdown.

There are other, more subtle aspects to Markdown and the Pandoc flavour of Markdown, but what we have seen above (and in our previous post) should cover most of the things we would use on a regular basis in scientific document preparation. This puts us a great position to move on to the next concept we will be looking into: modifying our output document using command line flags and yaml code blocks. Sounds confusing and mysterious? Great! You will definitely find the next post in this series enlightening.