363 lines
No EOL
9.3 KiB
Markdown
363 lines
No EOL
9.3 KiB
Markdown
---
|
||
title: "Markdown formatting guide"
|
||
date: "2023-06-28T01:58:32+03:00"
|
||
author: "anybody"
|
||
contributors: ["constantinos-miltiadis.md"]
|
||
draft: true
|
||
keywords:
|
||
- draft
|
||
abstract: |
|
||
This is a Markdown formatting guide.
|
||
---
|
||
|
||
# What is Markdown
|
||
|
||
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.
|
||
|
||
em dash -- with some content inside -- is useful.
|
||
|
||
*Formatting:*
|
||
```
|
||
This will
|
||
appear as
|
||
a single
|
||
line.
|
||
```
|
||
|
||
*Appearance:*
|
||
This will
|
||
appear as
|
||
a single
|
||
line.
|
||
|
||
## Text formatting
|
||
|
||
| Formatting | Appearance|
|
||
|-|-|
|
||
|`normal text`| normal text|
|
||
| `*emphasis*`| *emphasis*|
|
||
| `**bold**`| **bold**|
|
||
| `***bold emphasis***`| ***bold emphasis***|
|
||
| `~~strikethrough~~`| ~~strikethrough~~|
|
||
| \`code blocks\`| `code blocks`|
|
||
| `something<sup>superscript</sup>` | something<sup>superscript</sup>|
|
||
| `something<sub>subscript</sub>` | something<sub>subscript</sub> |
|
||
| `\* \~ \[ \{ \#` | \* \~ \[ \{ \#|
|
||
|
||
## Headings
|
||
|
||
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*:
|
||
```
|
||
|
||
**Figure 1: Sample illustration in SVG.**
|
||
|
||
|
||
**Figure 2: Sample illustration in PNG**
|
||
```
|
||
|
||
*Appearance*:
|
||
|
||
|
||
|
||
**Figure 1**: Sample illustration in SVG (vector format).
|
||
|
||
**Figure 2**: Sample illustration in PNG (raster format); exported from Illustrator: type-optimized, transparent background, size x3.
|
||
|
||
## Tables
|
||
|
||
*Table formatting*:
|
||
```
|
||
| Header 1 | Header 2 | Header 3|
|
||
|--|--|--|
|
||
| This | is | a|
|
||
| table | with | content.|
|
||
```
|
||
|
||
*Table appearance*:
|
||
| Header 1 | Header 2 | Header 3|
|
||
|--|--|--|
|
||
| This | is | a|
|
||
| table | with | content.|
|
||
|
||
Note: The number of dashes in the second row is arbitrary
|
||
|
||
---
|
||
|
||
In case alignment is important, it can be assigned per column.
|
||
|
||
- *Formatting*:
|
||
```
|
||
| Header 1 | Header 2 | Header 3|
|
||
|:--|:--:|--:|
|
||
| left | center | right|
|
||
```
|
||
|
||
- *Appearance*:
|
||
|
||
| Header 1 | Header 2 | Header 3|
|
||
|:--|:--:|--:|
|
||
| left | center | right|
|
||
|
||
|
||
For a table without headers, leave the initial row empty.
|
||
|
||
- *Formatting*:
|
||
|
||
```
|
||
| | |
|
||
|-|-|
|
||
|A|table|
|
||
|without|headers|
|
||
```
|
||
|
||
- *Appearance*:
|
||
|
||
| | |
|
||
|-|-|
|
||
|A|table|
|
||
|without|headers|
|
||
|
||
## Hyperlinks
|
||
|
||
- *Hyperlink formatting*:
|
||
|
||
```
|
||
[hyperlink caption](https://hyperlink-destination.org)
|
||
```
|
||
|
||
- *Hyperlink appearance*:
|
||
|
||
[hyperlink caption](https://hyperlink-destination.org)
|
||
|
||
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...
|
||
|
||
|
||
{{< youtube UEoDJ1v6U6U >}}
|
||
**Video 1**: Video caption.
|
||
|
||
{{< vimeo 55073825 >}}
|
||
**Video 2**: Video caption.
|
||
|
||
Formatting (replace square brackets with curly brackets):
|
||
```
|
||
[[< youtube UEoDJ1v6U6U >]]
|
||
**Video 1: Description.**
|
||
|
||
[[< vimeo 55073825 >]]
|
||
**Video 2: Description.**
|
||
```
|
||
|
||
|
||
### GitHub Gists
|
||
|
||
{{< gist cmiltiadis 0c458dcea8b8569398f5988b0151636c >}}
|
||
|
||
Formatting (replace square brackets with curly brackets):
|
||
```
|
||
[[< gist username gistId >]]
|
||
```
|
||
|
||
### Videogame embedding
|
||
|
||
Implement Unity WebGL embed described here:
|
||
https://michaelcassidy.net/post/hugo-shortcode-for-embedding-unity-webgl-players-updated-with-code/
|
||
|
||
This should allow embedding games as follows (note: square brackets need to be replaced with curly brackets):
|
||
```
|
||
> [[< unity-webgl-player game
|
||
> Title="My cool game"
|
||
> width="1024" height="576"
|
||
> buildURL="https://somewhere.com/path/to/files/Build"
|
||
> buildFileName="webgl"
|
||
> playerID="" >]]
|
||
```
|
||
## Unused formatting
|
||
|
||
The following includes formatting that might be useful while writing, but has limited application in published material.
|
||
|
||
### Horizontal dash
|
||
|
||
Formatting
|
||
```
|
||
---
|
||
```
|
||
|
||
Appearance
|
||
|
||
---
|
||
Note: Leave an empty line before a horizontal dash.
|
||
|
||
### Toggle lists
|
||
|
||
- [ ] Unchecked toggle item.
|
||
- [x] Checked toggle item.
|
||
|
||
```
|
||
- [ ] Unchecked toggle item.
|
||
- [x] Checked toggle item.
|
||
```
|
||
|
||
### Comments
|
||
|
||
To comment out some content, so that it's ignored use HTML comment formatting as follows:
|
||
```
|
||
<!-- this will not appear-->
|
||
|
||
<!--
|
||
Comments
|
||
can be
|
||
multiline.
|
||
-->
|
||
```
|
||
|
||
|
||
# Notes
|
||
- For the original Markdown specification see [Markdown specification (John Gruber, 2004)](https://daringfireball.net/projects/markdown/).
|
||
- For a Markdown formatting guide see [Basic Syntax (markdownguide.org)](https://www.markdownguide.org/basic-syntax/). |