Markdown: The Basics

Martin Post

Markdown markup reference"

Basic Markdown Reference

Occasionally, clients and business partners will ask us about Markdown, so here is a very basic guide to this popular lightweight markup language.

Please note that this is only a basic, bare-bones Markdown reference document. There are many more verbose and detailed sources for Markdown, such as…

1. Basic text paragraphs

A paragraph requires no formatting at all.

Just write your content, followed by a carriage return. You can add line breaks, but you should not indent content.

It is better to keep your mouth closed 
and let people think you are a fool 
than to open it and remove all doubt.

Result:

It is better to keep your mouth closed and let people think you are a fool than to open it and remove all doubt.

2. Headings

Use leading hash characters followed by one or more spaces to create headings, from # for level 1 to ###### for level 6, like so:

## Demo: This is a level 2 heading

Here is some content.

### Demo: This is a level 3 heading

Here is some content.

### Demo: This is a level 4 heading

Here is some content.

Result:

Demo: This is a level 2 heading

Here is some content.

Demo: This is a level 3 heading

Here is some content.

Demo: This is a level 4 heading

Here is some content.

3. Inline text formatting: Bold, italics etc.

Use asterisks or underscores for emphasis:

Here is a sentence with some *italicised / emphasised*  words.

Here is a sentence with **strong emphasis**, 
usually displayed in __bold type__.

Subscript and Superscript: 
H~2~O is a liquid, 
and here’s a 100 m^2^ apartment.

Result:

Here is a sentence with some italicised / emphasised words.

Here is a sentence with strong emphasis, usually displayed in bold type.

Subscript and Superscript: H₂O is a liquid, and here’s a 100 m² apartment.

4. Lists

4.1 Simple unordered Lists

- This is list item 1 in this list
- This is list item 2 in this list \
  This is line 2 of list item 2.

Result:

This is list item 1 in this list
This is list item 2 in this list
This is line 2 of list item 2.

4.2 Nested unordered Lists

Indent list items for nesting:

- This is list item 1 in this list
- This is list item 2 in this list
  - This is list item 1 in this nested list
  - This is list item 2 in this nested list
- This is list item 3 in this list

Result:

This is list item 1 in this list
This is list item 2 in this list
- This is list item 1 in this nested list
- This is list item 2 in this nested list
This is list item 3 in this list

4.3 Simple Ordered Lists

You do not have to number lists correctly, but the starting number will be observed.

1. This is list item 1 in this list
1. This is list item 2 in this list

Result:

This is list item 1 in this list
This is list item 2 in this list

4.4 Nested Ordered Lists

This is a ordered list starting at 2.
This is list item 2 in this list
1. This is list item 1 in this nested list
2. This is list item 2 in this nested list
This is list item 3 in this list

Result:

This is a ordered list starting at 2.
This is list item 2 in this list
1. This is list item 1 in this nested list
2. This is list item 2 in this nested list
This is list item 3 in this list

5. Tables

You can align tables properly using a monospaced font, with each element aligned, like so:

Head Cell 1    Head Cell 2    Head Cell 3   
-------------- -------------- --------------
Row 1 Cell 1   Row 1 Cell 2   Row 1 Cell 3  
Row 2 Cell 1   Row 2 Cell 2   Row 2 Cell 3  
Sum 1          Sum 2          Sum 3         

: Table 1 caption

Result:

Table 1 caption
Head Cell 1	Head Cell 2	Head Cell 3
Row 1 Cell 1	Row 1 Cell 2	Row 1 Cell 3
Row 2 Cell 1	Row 2 Cell 2	Row 2 Cell 3
Sum 1	Sum 2	Sum 3

…or you can just be “sloppy” and use separator characters (“|” and “-”) without proper spacing to create simple pipe tables:

Head Cell 1 | Head Cell 2 | Head Cell 3, which is longer than the others
--- | --- | ---
Row 1 Cell 1 | Row 1 Cell 2 | Row 1 Cell 3
Row 2 Cell 1, which is fairly long. | Row 2 Cell 2 | Row 2 Cell 3
Row 3 Cell 1 | Row 3 Cell 2 | Row 3 Cell 3
Sum 1 | Sum 2 | Sum 3

: Table 2 caption

Please note that this table notation style does not allow for paragraphs / line breaks in table cells.

Result:

Table 2 caption
Head Cell 1	Head Cell 2	Head Cell 3, which is longer than the others
Row 1 Cell 1	Row 1 Cell 2	Row 1 Cell 3
Row 2 Cell 1, which is fairly long.	Row 2 Cell 2	Row 2 Cell 3
Row 3 Cell 1	Row 3 Cell 2	Row 3 Cell 3
Sum 1	Sum 2	Sum 3

Align tables column content using colons in the separator line between header and body:

Default| Left | Right | Center 
-------|:-----|------:|:------:
1      |  1   |  1    | 1
12     |  12  |  12   | 12
123    |  123 |  123  | 123

: Table 3 caption

Result:

Table 3 caption
Default	Left	Right	Center
1	1	1	1
12	12	12	12
123	123	123	123

6. Links

6.1 Automatic Links

Please send me an e-mail to <mp@9to5.de>.

See the website <https://google.com/>.

Result:

Please send me an e-mail to mp@9to5.de.

See the website https://google.com/.

6.2 Direct Links

A paragraph [with an inline link to Google](https://google.com/).

Result:

A paragraph with an inline link to Google.

6.3 Reference Links

Reference links are a powerful concept, but maintaining these links requires more discipline, as the link (text) and its definition can be located in different parts of the document.

A link to the [Google home page][GoogleHome].

And here is a link to the [English Wikipedia entry][GoogleWiki] on Google.

[GoogleHome]: https://google.com/
[GoogleWiki]: https://en.wikipedia.org/wiki/Google 
  {title="Additional information about this link"}

Result:

A link to the Google home page.

And here is a link to the English Wikipedia entry on Google.

6.4 In-document Links

A direct link to a section in this document called [6. Links].

Result:

A direct link to a section in this document called 6. Links.

Important: Changing the title text will break the link.

7. Images

For using images, you’ll need to know and use the (relative or absolute) URLs of those images.

7.1 Locally defined images

An inline image: ![Description](https://assets.specs-and-docs.online/images/9to5/image_small.png)

An image in its own paragraph, which will be converted to a figure with a caption when using a modern Markdown converter:

![This is the image caption](https://assets.specs-and-docs.online/images/9to5/image.png)

Result:

An inline image: Description

An image in its own paragraph, which will be converted to a figure with a caption when using a modern Markdown converter:

7.2 Referenced images

Just like reference links, reference images are a powerful concept, but working with these reference images requires more discipline, as the image placeholder and its definition (with the URL and additional information such as width and CSS class) can be located in different parts of a document.

An image in a paragraph (referenced): 
![Alternative text][testimage1] 
and some text right after that image.

[testimage1]: https://assets.specs-and-docs.online/images/9to5/image_colored_small_extra.png

Result:

An image in a paragraph (referenced): Alternative text and some text right after that image.

8. Footnotes

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

[^1]: Here is the actual footnote. The footnote text follows directly in the source document, but should be shown at the end of the document in the created document.

[^longnote]: Here is a footnote with multiple blocks. The footnote text follows directly in the source document, but should be shown at the end of the document in the created document.

    Subsequent paragraphs are indented to show that they belong to the previous footnote.

Result:

Here is a footnote reference,¹ and another.²

9. Metadata

In most Markdown implementations, you can add metadata to the top of the document, like so:

---
title: "Title of the document"
document-date: "2024-07-01"
---

If and how these metadata fields will be processed depends on your Markdown converter, the target formats and templates being used.

Here is the actual footnote. The footnote text follows directly in the source document, but should be shown at the end of the document in the created document.↩︎
Here is a footnote with multiple blocks. The footnote text follows directly in the source document, but should be shown at the end of the document in the created document.

Subsequent paragraphs are indented to show that they belong to the previous footnote.↩︎

↻ 2024-06-27