Org Markdown Syntax Guide

This article started life as a cheatsheet for me as I was was trying to work out how my new website using Hugo - a framework for building websites, actually works:

How to write a document in Pandoc which would cover everything I need (this article more than truly covers all the elements I would ever use).
How to adjust the Bootstrap 4 SCSS styling so that the document would be rendered to suit my personal taste - for example tables.
Create a sample document with everything in it so that I could check that all of my styles worked properly including those elements that would not normally be written in a document such as the base text colour sets provided by Bootstrap 4.

The way I have written this article is to show the rendered text first such as this which will then be followed by the Pandoc syntax in:this colour.=

Headings

Unlike Markdown or pandoc, org headings start at H2, which kinda makes sense as you want to keep H1 for the page title.

H2 Bootstrap Heading

* H2 Bootstrap Heading

H3 Bootstrap Heading

** H3 Bootstrap Heading

H4 Bootstrap Heading with emphasis

*** H4 Bootstrap Heading with **emphasis**

H5 Bootstrap Heading

**** H5 Bootstrap Heading

H6 Bootstrap Heading

***** H6 Bootstrap Heading

Paragraphs

Here's a line for us to start with.

This line is separated from the one above by two newlines, so it will be a separate paragraph.

This line is also a separate paragraph, but…
This line is only separated by a single newline followed by two slashes at the end to create a hard break, so it's a separate line in the same paragraph.

This line is also a separate paragraph, but...\\\\
This line is only separated by a single newline followed by two slashes at the end to create a hard break, so it's a separate line in the *same paragraph*.

Inline Formatting

This text is italicized, bold, underlined,:verbatim=, -code- and ~~strikethrough~~.

This text is /italicized/, *bold*, _underlined_,:verbatim=:, -code- and ~~strikethrough~~.=

H₂O is a liquid. 2¹⁰ is 1024.

H_2O is a liquid. 2^10 is 1024.

Blockquotes

The blockquote element represents content that is quoted from another source, optionally with a citation which must be within a:footer= or:cite= element, and optionally with in-line changes such as annotations and abbreviations.

Blockquote without attribution

> Tiam, ad mint andaepu dandae nostion secatur sequo quae. > Note that you can use Markdown syntax within a blockquote.

Blockquote with attribution

> Don't communicate by sharing memory, share memory by communicating.</p> > — <cite>Rob Pike[^1]</cite>

[^1]: The above quote is excerpted from Rob Pike's [talk](https://www.youtube.com/watch?v=PAAkCSZUG1c) during Gopherfest, November 18, 2015.

Tables

Org tables rendered in Hugo are pretty basic and column alignment does not work so everything is left aligned but at least org allows you easily format the table using the #+CAPTION: and #+ATTR_HTML: attributes.

ID	First	Last	Handle
1	42	42	kahsjd
Mark	foobar	foobar	sdfg
	kjhk	kjhkhkjh
Geoff	kajshdf	jhg	yu
Wally is a numpty	kjh lkjsdf ksdhfkjnasdf kjhsadf khasdf kjhkhadf oihaerf khjasdfo iuyhasdf kjhasdf	jhkjhkjhkjh kjsdf kjhasdfk kjhdhh kjhasdfkh kjsdhfkoiu	Ohhh yeah jhgjgjgk

table with aligned columns

HTML tables

Well at least with an html table you can use Bootstrap's table styling properly.

ID	First	Last	Handle
1	Mark	Otto	@mdo
2	Jacob	Thornton	@fat
3	Larry	the Bird	@twitter

<table class="table table-striped table-bordered">
  <thead>
    <tr>
      <th scope="col">ID</th>
      <th scope="col">First</th>
      <th scope="col">Last</th>
      <th scope="col">Handle</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <th scope="row">1</th>
      <td>Mark</td>
      <td>Otto</td>
      <td>@mdo</td>
    </tr>
    <tr>
      <th scope="row">2</th>
      <td>Jacob</td>
      <td>Thornton</td>
      <td>@fat</td>
    </tr>
    <tr>
      <th scope="row">3</th>
      <td>Larry</td>
      <td>the Bird</td>
      <td>@twitter</td>
    </tr>
  </tbody>
</table>

Blocks

Source Code Block

a source block without a language

an example block

a quote block

a verse block

#+BEGIN_SRC

a source block without a language

#+END_SRC

#+BEGIN_EXAMPLE an example block #+END_EXAMPLE

#+BEGIN_QUOTE a quote block #+END_QUOTE

#+BEGIN_VERSE a verse block #+END_VERSE

@@html:<code class"verbatim">de>@@:

Code block with Hugo's internal highlight shortcode

Use Hugo's highlight shortcode to highlight code, for example with html:\{\{\< highlight html \>\}\} a bunch of html code \{\{\< /highlight\>\}\}</span>=

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Example HTML5 Document</title>
</head>
<body>
  <p>Test</p>
</body>
</html>

List Types

Ordered List

This is the first list:

First item
Second item
Third item

This is the second list:

Another first item - note that list numbering is reset and the number is ignored
Another second item - subsequent list numbers are ignored (24)
Another third item - and will be automatically incremented

This is the first list:

1. First item
2. Second item
3. Third item

This is the second list:

13. Another first item - note that list numbering is reset and the number is ignored
24. Another second item - subsequent list numbers are ignored (24)
3. Another third item - and will be automatically incremented

Unordered List

List item
Another item
And another item

- List item
- Another item
- And another item

Nested list

Item
1. First Sub-item indented
2. Second Sub-item indented

- Item
  1. First Sub-item indented
  2. Second Sub-item indented

Task list

an unchecked task list item
[x] checked item

- [ ] an unchecked task list item
- [x] checked item

Definition List

Definition lists have the following syntax:- Term :: Definition=. Terms and definitions can be nested.

Term 1

Definition 1

Term 2

Definition 2a Definition 2b

Term 3

Definition 3

Nested Term 4

Nested Definition 4 - nested items need to be indented by 4x spaces

A second paragraph of the definition

Nested Term 5

Nested Definition 5

- Term 1 :: Definition 1

- Term 2 ::
  Definition 2a  
  Definition 2b

- Term 3 ::
  Definition 3

  + Nested Term 4 ::
    Nested Definition 4 - nested items need to be indented by 4x spaces

    A second paragraph of the definition

  + Nested Term 5 ::
    Nested Definition 5

Links

This is an internal link to the Images section and this is a link to the Pandoc website.

This is an internal link to the [[#images][Images]] section and this is a link to the [[https://pandoc.org][Pandoc]] website.

Images

/gallery/2017/2017_01_7-8/20170107-_O156345_DxO.jpg — Image Caption

With images you can specify any attribute you like. In this case this text flows around the right hand side of the image.

  #+CAPTION: Image Caption
  #+ATTR_HTML: :class img-fluid my-3 mr-3 :style width: 50%
  [[/gallery/2017/2017_01_7-8/20170107-_O156345_DxO.jpg]]

With images you can specify any attribute you like. In this case this text should flow around the right hand side of the image.

You will also need to add a:<div class="clearfix"></div>= element to prevent subsequent text such as the <span class="text-primary"> References </span> section below from flowing around the image.

Footnotes

And almost finally ¹ this is a footnote which will be displayed at the bottom of this section.

Some additional text to test that the footnote will appear below this - note that you need to insert two blank lines after the footnote to ensure that this line is not part of the footnote.

And almost finally [fn:1] this is a footnote which will be displayed at the bottom of this section.

[fn:1]: Note that the footnote marker must not contain any whitespace. 


Some additional text to test that the footnote will appear below this - note that you need to insert two blank lines after the footnote to ensure that this line is not part of the footnote.

Note that the footnote marker must not contain any whitespace.