Markdown

luis@hellerwach

#markdown

Markdown is a lightweight markup language for creating formatted text using a plain-text editor. John Gruber and Aaron Swartz created Markdown in 2004 as a markup language that is appealing to human readers in its source code form. Markdown is widely used in blogging, instant messaging, online forums, collaborative software, documentation pages, and readme files. – https://en.wikipedia.org/wiki/Markdown [2022-07-21]

Using Markdown #

Some services (e.g. GitHub, Hugo etc.) convert Markdown automatically whilst for your own usage, you might have to convert it manually.

However, due to the popularity of Markdown, this is no problem. There are many libraries in essentially all programming languages and tools in the CLI or on the Web. Sometimes your text editor might also include a converter.

For example:

The file extension is .md.

Syntax #

Markdown has a simple, easy-to-write, easy-to-read syntax. The original, very minimal, definition was written by John Gruber. However, it has been largely superseded by CommonMark (latest CommonMark specification). Most parsers, converters and tools support CommonMark, but there are also a number of extensions like GitHub Flavored Markdown.

Paragraphs #

Lorem ipsum dolor sit amet, pharetra enim nibh sociosqu natoque quisque
facilisis dignissim malesuada hac risus dignissim dolor arcu et. Tortor lacus
ligula rutrum laoreet habitasse vel arcu maecenas. Non posuere a viverra
suspendisse cursus cubilia torquent duis gravida vehicula senectus vivamus
velit. Arcu class blandit mi dolor vel cras magnis sit cubilia. Nisl duis et
proin pulvinar lectus nibh vulputate mi. Justo habitasse a conubia mus duis ad
mus torquent eget mollis tempor rhoncus.

Another paragraph.
<p>
  Lorem ipsum dolor sit amet, pharetra enim nibh sociosqu natoque quisque
  facilisis dignissim malesuada hac risus dignissim dolor arcu et. Tortor lacus
  ligula rutrum laoreet habitasse vel arcu maecenas. Non posuere a viverra
  suspendisse cursus cubilia torquent duis gravida vehicula senectus vivamus
  velit. Arcu class blandit mi dolor vel cras magnis sit cubilia. Nisl duis et
  proin pulvinar lectus nibh vulputate mi. Justo habitasse a conubia mus duis ad
  mus torquent eget mollis tempor rhoncus.
</p>
<p>Another paragraph.</p>

Line breaks #

Line breaks can be added to a line by either including two spaces at the end or with a backslash.

NOTE: symbolizes a space.

Verse1 \
Verse2

Verse1␣␣
Verse2
<p>
  Verse1<br />
  Verse2
</p>

<p>
  Verse1<br />
  Verse2
</p>

Headings #

Alternatively, one can use Setext headings.

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6
<h1>Heading 1</h1>
<h2>Heading 2</h2>
<h3>Heading 3</h3>
<h4>Heading 4</h4>
<h5>Heading 5</h5>
<h6>Heading 6</h6>
[Link](https://example.org/)

[Link][1]

[1]: https://example.org/

<https://example.org>
<p><a href="https://example.org/">Link</a></p>
<p><a href="https://example.org/">Link</a></p>
<p><a href="https://example.org/">https://example.org</a></p>

Images #

Images are like links, but with a ! in front of them. They can also contain a link label ([identifier]).

![Wikipedia Logo](https://upload.wikimedia.org/wikipedia/en/8/80/Wikipedia-logo-v2.svg "Title")
<p>
  <img
    src="https://upload.wikimedia.org/wikipedia/en/8/80/Wikipedia-logo-v2.svg"
    alt="Wikipedia Logo"
    title="Title"
  />
</p>

Emphases #

Italics #

*This text* is italic.

_This text_ is also italic.
<p><em>This text</em> is italic.</p>
<p><em>This text</em> is also italic.</p>

Boldface #

Boldface text is created by surrounding text with either two * or two _.

**This text** is bold.

__This text__ is also bold.
<p><strong>This text</strong> is bold.</p>
<p><strong>This text</strong> is also bold.</p>

Together #

Italics and boldface can be used together.

***This text*** is bold and italic.

**_This text_** is also bold and italic.
<p>
  <strong><em>This text</em></strong> is bold and italic.
</p>
<p>
  <strong><em>This text</em></strong> is also bold and italic.
</p>

Blockquotes #

> Lorem ipsum...
>
> > A nested blockquote.
<blockquote>
  <p>Lorem ipsum...</p>

  <blockquote>
    <p>A nested blockquote.</p>
  </blockquote>
</blockquote>

Code #

Inline #

Inline code is created by surrounding it with backticks.

`This text` is inline code.
<p><code>This text</code> is inline code.</p>

Code Blocks #

Code blocks can be created by indenting the code or surrounding it with three backticks or tildes (~).

```
code
another line
```
<pre><code>code
another line
</code></pre>

It is common to see a language specification for syntax highlighting. For example specifying go.

```go
package main
...
```

This will get Go syntax highlighting by GitHub and other services.

<pre><code>package main
...
</code></pre>

Lists #

Unordered lists can be created by preceding every list item with a -, * or +. Indentation with a tab and a -, * or + creates a sub list. Without them the list item will contain another paragraph.

NOTE: symbolizes a tab character.

Unordered #

- item 1
- item 2
⇥- item 2.1
- item 3
<ul>
  <li>item 1</li>
  <li>item 2</li>
  <ul>
    <li>item 2.1</li>
  </ul>
  <li>item 3</li>
</ul>

Ordered #

Ordered lists can be created by preceding every list item with a 1. or 1). Indentation with a tab creates a sub list.

NOTE: symbolizes a tab character.

1. item 1
2. item 2
⇥2.1 item 2.1
3. item 3
<ol>
  <li>item 1</li>
  <li>item 2</li>
  <ol>
    <li>item 2.1</li>
  </ol>
  <li>item 3</li>
</ol>

Horizontal rule #

A horizontal rule can be added with three - or * on a line.

---
<hr />

GitHub Flavored Markdown #

Striketrough #

Text surrounded by two ~ appears striketrough.

~~This text~~ is striketrough.
<p><s>This text</s> is striketrough.</p>

Task Lists #

Tasks lists are unordered lists with a [ ] or [X] (any character for that matter) directly following the -. They can be nested like normal unordered lists.

- [ ] task 1
- [x] task 2
<ul>
  <li><input disabled="" type="checkbox" /> task 1</li>
  <li><input checked="" disabled="" type="checkbox" /> task 2</li>
</ul>

Autolink enables the recognition of links without a special syntax.

www.example.org

email@example.org
<p><a href="https://www.example.org">www.example.org</a></p>
<p><a href="mailto:email@example.org">email@example.org</a></p>

Tables #

ASCII tables are recognized in GFM. Due to them being tedious to write by hand, there are tools to remedy.

The orientation of a column can be changed with : like shown in the example below. Everything below item is aligned to the left, everything below price to the right and the colors are centered. More complex tables have to be written in HTML.

The spacing in every table entry are only for aesthetic reasons.

| Item  | Color | Price |
| ----- | :---: | ----: |
| Apple |  Red  |    $3 |
| Apple | Green |  $2.5 |
<table>
  <thead>
    <tr>
      <th>Item</th>
      <th style="text-align:center">Color</th>
      <th style="text-align:right">Price</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Apple</td>
      <td style="text-align:center">Red</td>
      <td style="text-align:right">$3</td>
    </tr>
    <tr>
      <td>Apple</td>
      <td style="text-align:center">Green</td>
      <td style="text-align:right">$2.5</td>
    </tr>
  </tbody>
</table>

Other extensions #

Footnotes #

Footnotes will render differently according to your converter. However, this is how you create them.

This is text[^1].

[^1]: and this is a footnote.

Subscript #

H~2~O
<p>H<sub>2</sub>O</p>

Superscript #

y=f(x)=x^2
<p>y=f(x)=x<sup>2</sup></p>

MathJax #

Some converters also support MathJax/(La)TeX commands.

$\LaTeX$

Will get be shown as LaTeX formatted as you know it.

Emoji #

Either insert an Emoji as a character or use emoji shortcodes.

🔥 blazingly fast

:fire: blazingly fast
<p>🔥 blazingly fast</p>
<p>&#x1f525; blazingly fast</p>

Definition Lists #

MUST
: This word, or the terms "REQUIRED" or "SHALL", mean that the definition is an absolute requirement of the specification.
<dl>
  <dt>MUST</dt>
  <dd>
    This word, or the terms &ldquo;REQUIRED&rdquo; or &ldquo;SHALL&rdquo;, mean
    that the definition is an absolute requirement of the specification.
  </dd>
</dl>

Aesthetics #

Since Markdown was also invented as a nice looking markup language, it is recommended having a uniform look in the documents. The following notes are just personal preferences that you may also enjoy.

Headings #

Headings should have an empty line above and below them to distinguish them better from the enclosing text.

some text ...

## Heading 2

some text ...

Emphases #

Without any syntax highlighting it is easier to think of text with an underscore (_) as italicized and text with two asterisks (**) as boldfaced.

_This text_ is italicized. **And this** is boldfaced.

Blockquotes #

To add a source to a blockquote, consider doing this:

> Lorem ipsum dolar sit amet.
> -- <https://en.wikipedia.org/wiki/Lorem_ipsum>

Lists #

Personally, I think lists starting with a - look more like bullet point lists as you would write them by hand. That’s why I prefer them.

GFM #

Task Lists #

Checked tasks should have a lowercase or uppercase x in them, because it looks more like a task crossed as done. Having a tick () in them would require you to paste it every time, as it is not commonly found on keyboard.

Tables #

Every column of a table should have the same amount of characters in them to have a more homogeneous look.

Consider the difference in readability between these tables.

| Item  | Color | Price |
| ----- | :---: | ----: |
| Apple |  Red  |    $3 |
| Apple | Green |  $2.5 |
| Item  | Color | Price |
| ----- | :---: | ----: |
| Apple |  Red  |    $3 |
| Apple | Green |  $2.5 |