Markdown

Markdown is a markup language for writing and formatting in plain text. Its great advantage over HTML is the much improved readability and its advantage over specialized formats, like Word documents, is the portability of plain text.

A Word document requires you to have Word installed, plain text requires you to just have any text editor. Derek Sivers in his “Write plain text files” post goes into a deeper explanation of why plain text is such an excellent format. He speaks about .txt files directly, but Markdown can act like a .txt and does not need to be converted into a different format to have excellent readability.

While converting Markdown into HTML is not required, it is a very common thing to do. Discord, reddit, and Github are among the places where users can write Markdown and have it turned into HTML. It’s safe to assume that many badly formatted posts on a platform like reddit were caused by Markdown.

Because the program that turns Markdown into HTML is controlled by the website or application, websites often add additional formatting rules beyond those found in the CommonMark specification. Some extensions, like strikethrough text using the ~~strikethrough~~ syntax, are widespread enough to appear in many implementations despite not being part of the official spec.

This site uses markdown-it as its Markdown parser. This page shows off the basic CommonMark support and the various extensions.

Inline formatting

Markdown supports most of the basic formatting you would expect from any text editor. These are often called “inline” elements because they can be used inline with flowing prose without interrupting it.

Emphasis

Markdown allows text to be written in italics and bold using asterisks (*) or underscores (_). A common extension allows for two tildes (~~) to be used for strikethrough text.

The Markdown that created the above paragraph looks like this:

Markdown allows text to be written in _italics_ and **bold** using asterisks
(`*`) or underscores (`_`). A common extension allows for two tildes (`~~`) to
be used for ~~strikethrough~~ text.

Links

Links can be created using [square brackets] followed by the link in (round brackets). A link inviting you to read thiem.xyz would look like this:

[read thiem.xyz](https://thiem.xyz)

Many Markdown parsers also have the ability to “linkify” text that looks like a URL. This is supported by markdown-it and thus simply using the URL to my blog works too: https://thiem.xyz.

On this site external links are highlighted with the favicon of the website it’s pointing to, as is happening here with the Wikipedia favicon.

Indicating code

An inline code block is created by using backticks (`). A paragraph recommending printf() debugging would be written like so:

Despite many advancements in debugger technology, using `printf()` is still
considered the best and most efficient way to debug code.

Footnotes

Footnotes blur the line between inline and block elements. This is a footnote: 1. They are created using [^x] where x is any number or text. To create the content of the footnote [^x]: is created in a new paragraph.

The plugin — footnotes are not in CommonMark, but instead are a common extension — will then place the content of the footnote at the end of the document. It is useful to keep the footnote and its content close together for ease-of-editing.

The syntax to create the footnote above is:

This is a footnote: [^1].

[^1]: Hey, there. I am a footnote.

A footnote whose label is words rather than a number is given a title 2, shown above the note wherever it appears. Numbered labels stay untitled, so naming one is a choice made per footnote.

Footnotes support all the formatting you are used to from Markdown. I would recommend showing some restraint with the number and length of footnotes 3.

Block elements

Block elements can’t be placed within a paragraph, instead they create a new one. Some fairly advanced formatting can be achieved this way.

Paragraphs and line breaks

One of the first oddities that a new user of Markdown is likely to encounter is Markdown’s rules around new lines. A single new line is considered “hard-wrapping” of the text, essentially allowing the plain text representation to limit the characters per line of text. When rendered out this does then produce a single paragraph of text where a user might have expected multiple.

To create a new paragraph in Markdown an empty line between the two paragraphs is required. The syntax looks like this:

First paragraph.
Still the first paragraph.

Second paragraph.

Headers

Headers are created with the hashtag number sign (#). The more # are used, the deeper nested the heading is.

# indicates the title of the document, ## the first subheading, and ### … you get the drift. Up to six # can be chained together, ranging from <h1> to <h6>. If your writing requires headings that deep, you should rethink some things including, but not limited to, the structure of your document — just saying.

The header for this section was created like so:

### Headers

Blockquotes

Blockquotes can be created with the greater-than sign (>). This is apparently what people used to do in emails; I am sure there are dozens of people that remember that.

Attributed Quotes

A blockquote whose last line begins with an em or en dash is rendered as a <figure>, with that line lifted out into a <figcaption>. Emphasis inside the attribution becomes a <cite>:

Callouts

A blockquote that opens with a GitHub-style alert marker ([!name-of-callout]) becomes a callout instead. The marker has to stand alone on its line; everything after it is the body. If Prettier is used to format Markdown with prose wrap, the marker has to sit alone in a paragraph, otherwise the marker and the callout text will be merged.

Putting anything else on the marker’s line stops it from matching, and the blockquote falls back to an ordinary quote. A mistyped or over-filled marker shows up in the rendered page instead of silently dropping content.

Lists

Markdown supports ordered (numbered, <ol>) and unordered (bulleted, <ul>) lists.

Unordered lists use asterisks (*), pluses (+), or hyphens (-) as list markers:

• 12 Eggs
• 6 Milks
• 2 pairs of programmer socks

Ordered lists use numbers followed by periods:

1. Pineapple
2. Pepperoni
3. Spinach

Note that the numbers used in Markdown have no effect on the final HTML output. Numbering your lists using only 1. or out of order is perfectly valid Markdown.

As per usual, Markdown allows you to use other formatting within lists:

1. Yes, I believe that pineapple on pizza is tasty.

2. Those who decry pineapple on pizza have not understood pizza.

3. The rage-bait above was created like so:
   markdowncopy

   1.  _Yes_, I believe that **pineapple on pizza** is tasty.
   1.  > Those who decry pineapple on pizza have not understood pizza.
       >
       > — Albert Einstein, _not really_

Images

Markdown is often extended to support the inclusion of images and reuses the syntax for links. Simply prepend an ! before the [square brackets] to have a link interpreted as an image. The text inside the square brackets will be used as the image’s “alt text”.

An image expected to appear in the initial viewport can be loaded eagerly and given high fetch priority by appending {priority}. Use this for no more than one image per page:

![A description of the important image.](./important-image.jpg){priority}

Code Blocks

As this document has demonstrated repeatedly, pre-formatted code blocks can be used to write about programming or markup. In HTML they are represented as <pre> and <code> tags.

A code block is created using three backticks followed by the language that the block contains (```rust) and is closed again with three backticks on a new line.

fn main() {
  let name = "World";
  println!("Hello, {name}!");
}

The code to create code blocks is:

The code to create code blocks is:

```markdown
The code to create code blocks is ... I think two layers deep is far enough.
```

The language name is optional; code blocks can be created without it. But adding a language does allow a lot of markdown parsers to add syntax highlighting. Even some text editors, like my Neovim, will do so. This site uses Shiki for syntax highlighting.

Markdown will escape ampersands (&) and angle brackets (< and >) automatically when placed in code blocks. Additionally, Markdown in code blocks will not be touched. This makes it easy to write about HTML or Markdown itself in Markdown.

Look out, stray notes!
<span style="position: relative; bottom: 1ch; left: -7ch">🎶</span>

Modern web browsers support font ligatures:

== === -> => <-> <> ... !== := 0xfff

## ### |-|---| ?. ?? !! /\ \/ <|| || |> ||>

That really has little to do with code blocks, I just wanted to show that off. Pretty cool, huh?

HTML escape hatch

Some Markdown parsers allow the use of raw HTML in Markdown. This can be useful when fine-grained control over formatting is required.

The HTML from the last section pasted into Markdown raw creates:

Look out, stray notes! 🎶