Markdown is an open standard for a flexible, human-readable, lightweight mark-up language for formatting text. It was developed by John Gruber and the late Aaron Swartz, and released in 2004. Markdown files have the extension ‘*.md*’ and consist of plain text. Therefore Markdown files can be opened, edited and ready using any text editor, rudimentary or otherwise.
Since its release Markdown was adopted widely for multiple applications. For example by *GitHub* (for readme files), by R (as R Markdown), for note-taking and collaborative writing (e.g. *Obsidian*, *hackmd.io*, *Zotero*, *Nextcloud*), for chat applications (e.g. *Element*), and also by static website frameworks (e.g. *Hugo* and *Jekyll*).
Although one can write in Markdown in a rudimentary notepad, it is recommended to use a text editor such as [Obsidian](https://obsidian.md/), or [Visual Studio Code](https://code.visualstudio.com/.). For an online Markdown editor see [hackmd.io](https://hackmd.io/).
For further resources on Markdown see [notes](#notes).
# Markdown formatting guide
## Writing in Markdown
Markdown is a plain text format, intended for digital text.
It's unlike conventional word processors that simulate writing on paper and follow the what-you-see-is-what-you-get (WYSIWYG) concept.
Markdown is intended to facilitate writing and reading.
Headings make use of the hashtag character, as follows:
```
# Heading
## Sub-heading
### Sub-sub-heading
```
Note that a space is required between the hashtag character and the header text.
## Lists
Markdown bullet lists use the dash/minus symbol as in:
```
- bullet item
```
Numbered lists start with a number followed by a period as in:
```
1. list item
```
Note that both cases require a space before the list item text.
To add depth, add two spaces or a tab in a subsequent list item.
### Bullet lists
Bullet list formatting:
```
- bullet 1
- bullet 2
- sub-bullet 2.1
```
Bullet list appearance:
- bullet 1
- bullet 2
- sub-bullet 2.1
### Numbered lists
Numbered list formatting:
```
1. List item 1,
2. List item 2,
1. Sub-item 2.1
```
Numbered list appearance:
1. List item 1,
2. List item 2,
1. Sub-item 2.1
## Quotes
*Blockquotes:*
> This is a blockquote. Block quotes should be used when the quoted text is 40 words or more. Otherwise use in-line quotes. In all cases quotes are followed by a reference (Author et. al 2010).
*Blockquote formatting:*
```
> This is a blockquote. Block quotes should be used when the quoted text is 40 words or more. Otherwise use in-line quotes. In all cases quotes are followed by a reference (Author et. al 2010).
```
*Inline quotes:*
For shorter quotes, use inline quotes, between "quotation marks" and should be followed by a reference (Author 2015).
Note that:
- > If *you emphasized some text yourself you need to mention that in the reference* (Author et al. 2010; emphasis mine).
- > Or if your quote includes an *emphasis found in the original* (Author et al. 2020, emphasis in original).
- If your inline quote includes a world
- [how to mention 'et al.' : Author and colleagues or Author et al.?]
- [example of normal in-line quote]
- [omitting author from ref] Discussing x, Author described that "this is a good case of" (2010).
- [example of quote edit]
- [example of transcript]
- [example of emphasis]
## Images
Recommended and supported image formats are:
- PNG for rasterized content.
- SVG for vector content.
Avoid image formats that are lossy and can introduce artifacts (e.g. JPG).
*Image formatting pseudocode*:
```
**Figure 1**: Caption text.
```
*Image formatting example*:
```
Note: Do not omit the `http://` or `https://` part of the URL.
## Internal Links
To link to another section of the same document, use the hyperlink syntax.
For destination use the heading of the section, in lowercase, replacing spaces with dashes. Prefix that with only one hashtag character, regardless of the depth of the heading.
Formatting example (a link to the first section of this document):
[go to 'What is Markdown'](#what-is-markdown).
Syntax:
```
[go to 'What is Markdown'](#what-is-markdown)
```
## Footnotes
The syntax for inserting a footnote is `[^key]`, where `key` can be arbitrary. The content of the footnote can be placed anywhere in the document, and follows the syntax `[^key]: Footnote content.`
Here is a sentence with a footnote.[^fn] Footnotes are placed *after* a period or comma, like here.[^fn] Footnotes can be reused, and Sandpoints will generate dynamic backlinks to all mentions of the same footnote.[^fn]
[^fn]: This is the text of a footnote, used 3 times.
Formatting:
```
Here is a sentence with a footnote.[^fn]
[^fn]: This is the text of a footnote, used 3 times.
```
## Embedded content
Hugo can embed a range of different media via shortcodes (see [Hugo shortcodes](https://gohugo.io/content-management/shortcodes/)). Note that embedded media cannot be exported to PDF or printed.
More importantly,
YouTube, and Vimeo videos can be easily embedded using video ids (the last bit of their URLs). Embedded content should contain a caption including...
{{<youtubeUEoDJ1v6U6U>}}
**Video 1**: Video caption.
{{<vimeo55073825>}}
**Video 2**: Video caption.
Formatting (replace square brackets with curly brackets):
