Markdown Style Guide

Share

Below is a reference to markdown syntax, the first part of each will have the markdown syntax followed by what it looks like on the browser.

Block-level Elements - Main Structural Elements

Paragraphs

Consecutive lines of text are considered to be one paragraph. As with other block level elements you have to add a blank line to separate it from the following block-level element:

The first paragraph.

Another paragraph

Explicit line breaks in a paragraph can be made by using two spaces or two backslashes at the end of a line:

This is a paragraph
which contains a hard line break.

Headers

A header must always be preceded by a blank line except at the beginning of the document:

# H1 header
## H2 header
### H3 header

H1 header

H2 header

H3 header

H4 header

Blockquotes

A blockquote is started using the > marker followed by an optional space. You can use any block-level elements inside a blockquote:

> This is a blockquote

This is a blockquote

Horizontal Rules

Can insert a horizontal rule(hr tag) using:

* * *

The above three asterisks will result in:


Lists

Ordered lists are started by using a number followed by a period, a space and then the list item text. The content of a list item consists of block-level elements. All lines which have the same indent as the text of the line with the list marker belong to the list item:

1. This is a list item
2. And another item
3. And the third one

Will result in:

  1. This is a list item
  2. And another item
  3. And the third one

Unordered lists:

* A list item with additional text

Will result in:

  • A list item with additional text

Nested Lists

1. Item one
1. sub item one
2. sub item two
3. sub item three
2. Item two

Will result in:

  1. Item one
    1. sub item one
    2. sub item two
    3. sub item three
  2. Item two

Lists can occur directly after other block-level elements, however, there has to be at least one blank line if you want to follow a paragraph with a list.

Unordered lists are started by using an asterisk, a dash or a plus sign (they can be mixed) and a space. Apart from that unordered lists follow the same rules as ordered lists:

* Item one
+ Item two
- Item three

Will result in:

  • Item one
  • Item two
  • Item three

Emphasize elements:

This *is* a term

This is a term

Strong emphasis can be done by doubling the delimiters:

This is **strong**

This is strong

Tables

A line starting with a pipe character (|) starts a table row. If the pipe character is followed by an equal sign (=), the tables rows below it are part of the table footer.
| A simple | table |
| with multiple | lines|
A simple table
with multiple lines

Table with header and footer:

| Header1 | Header2 | Header3 |
|:------------|:-----------:|------------:|
| element1 | element2 | element3 |
|----
| element1 | element2 | element3 |
|=====
| Foot1 | Foot2 | Foot3
{: rules="groups"}
Header1 Header2 Header3
element1 element2 element3
element1 element2 element3
Foot1 Foot2 Foot3

Blank Lines

To add a blank line add the html <br /> tag.


HTML elements

Use block-level HTML tags (div, p, pre, …) to markup whole blocks of text – just start a line with a block-level HTML tag. kramdown syntax is normally not processed inside an HTML tag but this can be changed with the parse_block_html option. If this options is set to true, then the content of a block-level HTML tag is parsed by kramdown either as block level or span-level text, depending on the tag:

<div style="text-align: right"> Something that stays right and is not wrapped in a para. </div>
{::options parse_block_html="true" /}
<div> This is wrapped in a para. </div>
<p> This can contain only *span* level elements. </p>

Will result in:

Something that stays right and is not wrapped in a para.

This is wrapped in a para.

This can contain only span level elements.

Links

A simple link can be created by surrounding the text with square brackets and the link URL with parentheses:

A [link](https://flatmates.com.au/) to the Flatmates homepage.

Will result in :

A link to the Flatmates homepage.

There is another way to create links which does not interrupt the text flow. The URL and title for the link are defined using a reference name and this reference name is then used in square brackets instead of the link URL:

A [link][Flatmates homepage] to the homepage.
[Flatmates homepage]: https://flatmates.com.au/ "homepage"

A link to the homepage.

If the link text itself is the reference name, the second set of square brackets can be omitted:

A link to the [Flatmates homepage].
[Flatmates homepage]: https://flatmates.com.au/ "homepage"

A link to the Flatmates homepage.

To make the link open in a new tab use:
[link](https://flatmates.com.au/){:target="_blank"}

link

Images

Images can be created in a similar way: just use an exclamation mark before the square brackets. The link text will become the alternative text of the image and the link URL specifies the image source:

An image: ![house](https://img.flatmates.com.au/img/places/medium/-651660.jpg)

An image: house

Image caption

An optional image caption or credit can be added. This is a small grey text which is right hand justified and sits close to the bottom of the image.

For example add the following html right after the image:
<sup> Flatmates.com.au </sup>

surryhills

Flatmates.com.au

If you want to overwrite it, you could do something like:
<sup style="float: left; margin-top: 0"> Flatmates.com.au <sup>

Flatmates.com.au

Inline Code

Text phrases can be easily marked up as code by surrounding them with backticks:

`Array.new` is marked up as code

Array.new is marked up as code

Small text

Use the small tag. Add the text between <div class = "no-markdown-small" markdown = "0" > and </div> to prevent the text from being wrapped by a html p tag. Add blank lines before and after the no-markdown tags. For example:
<div class = "no-markdown-small" markdown = "0" >
<small> With thousands of listings across Australia and hundreds more added every day, finding a place is easy on Flatmates.com.au. </small>
</div>
With thousands of listings across Australia and hundreds more added every day, finding a place is easy on Flatmates.com.au.

Footnotes

To use footnotes, set a footnote marker (consists of square brackets with a caret and the footnote name inside) in the text and somewhere else the footnote definition (which basically looks like a reference link definition):

This is a text with a footnote[^1].
[^1]: And here is the definition.

This is a text with a footnote1.

HTML Elements

This is <span style="color: red">written in red</span>.

This is written in red.

For existing articles, to fix the auto ids that were generated for html headings like h1, just edit and save the article.

  1. And here is the definition.