Markdown for science and academia – basic formatting
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
Lists are a great way to represent information. A few types are available to us in Markdown.
* 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
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
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 -------------------------------------------------
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.
There are various styles of text blocks in Markdown, and the Pandoc flavour of Markdown.
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:
These can be included in our text by starting the line with the greater-than symbol
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:
As mentioned in our previous post, we can include computer code to our Pandoc flavoured Markdown file.
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:
A horizontal line, to separate two sections of test, can be added by including four or more dashes.
will be rendered like the line separating these two sections of text:
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.