MarkdownPrimer

A Quick Pandoc Markdown Primer

A walkthrough of common markdown constructs you will need. This is a quick introduction and is no subsititute for RTFM https://pandoc.org/MANUAL.html

The report is written in markdown, a text based markup language (like HTML) that allows you to provide struture to the docuement using plain text.

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

You may be familair with Markdown from GitHub, or other project. Unfortunately, like many decent open source project, it does suffer from differnt project having different "Flavors"[^flavors]. However, about 99% of what you will need to do is compatable between versions.

[^flavors]: Or A Maze of Twisty Turny standards, all alike

Document Structure

The first thing we need to do is add some structure to our document. If you look back at the Introduction we created in Getting Started you can see we had some structure, with headings and subheadings breaking up the text.

My preferred way to setup section headings is to use the ATX format[^headers] Each header consists of a 1..6 # Signs followed by the header text

# Chapter / Section Header
## Header
### Sub Header 
#### Sub Sub Header

[^headers]: Other Header formats exist, including ReST style underlines.

NOTE: I prefer to have a seperate file for each Chapter / Section, (Ie Introduction.md, LitReview.md) I find it helps me to keep things organsed.

Text Formatting

You may also want to change the way text is formatted.

 - *Emphasis* (Itallic)
 - **Strong Emphasis** (Bold)
 - _Underline_ 
 - ~~Strikeout~~
 - Superscript 2^4^
 - Subscipt  H~2~0

• Emphasis (Itallic)
• Strong Emphasis (Bold)
• Underline
• Strikeout
• Superscript 2^4^
• Subscipt H20

We can also have Quotations

 > This is a quotation, the text will be displayed Verbatim.
 >
 > The quotation can span multiple Lines
 > 

Lists

Another way of structuring the report is to use lists. There are several types of list we may want to use.

1. Bullet Points
2. Numbered Lists
3. Definition Lists

As well as section headings, I like to use lists to help me structure the document. My own workflow for writing is to get the structure right, then use lists to outline the content of each section. Finally turning each of those bullet points into sentances.

Bullets

Are represented by either * + or - followed by a space then the list text.

 * First Item in the List
 * Second Item in the List
    * Nested List Item

Which renders as:

• First Item in the List
• Second Item in the List
  • Nested List Item

Ordered

Ordered lists work in the same way as bullets, but instead we use N. (where N is some integer), It doesnt matter what number is used, as pandoc will automagically start the numbering at 1

 1. Numbered List
 1. Second item in the list
   1. Nested item in the list

Which Renders as

1. Numbered List
2. Second item in the list
3. Nested item in the list

Lists containing long lines of text

Lists can contain multiple paragraphs, However, each paragraph must be intented to align with the first item in the list.

 * This is the first Item of my list
 
   We have a paragraph here that is part of the first item
   
 * Second Item 
 
   Paragraph for the Second item,
   More text for the Second item.

Tables

Source Codes

Images

Links

References