Markdown Reference

Kip Landergren

(Updated: )

My cheat sheet for Markdown covering common authoring examples and documentation links.

Contents

markdown-study

README.md

# markdown-study

Personal study area for [GitHub-flavored markdown](https://github.github.com/gfm/)

code.md

You can specify `inline code` or:

```
block level code
```

and, for GitHub, specify the [language](https://github.com/github/linguist/blob/master/lib/linguist/languages.yml):

```ruby
[1,2,3].map {|x| x * x }
```

to code fence code that itself has code fences:

````markdown
```ruby
puts "using more backticks than the contained works"
```
````

~~~markdown
```ruby
puts "using different delimiters like tildes also works"
```
~~~

headings.md

# top level heading

typically h1 equivalent

## second level heading

typically h2 equivalent

### third level heading

typically h3 equivalent

links.md

## HREFs

[link text](https://example.com)

## Anchor Links

[link to heading foo below](#Foo)

Difficulties:

* determining correct fragment (e.g. headings with complex characters)
* keeping up to date if heading title changes

### Foo

lists.md

## Unordered Lists

To add an item to an unordered list:

* indent zero spaces
* followed by a single:
  * asterisk (`*`)
  * dash (`-`)
  * plus (`+`)
* followed by a single space
* followed by text

Sublist items are indented sufficient to align with the beginning content of the parent (typically an additional two spaces).

All of the following are equivalent.

preferred:

* Item A
* Item B
* Item C
  * C Child 1
  * C Child 2

alternatives:

- Item A
- Item B
- Item C
  - C Child 1
  - C Child 2

+ Item A
+ Item B
+ Item C
  + C Child 1
  + C Child 2

## Ordered Lists

To add an item to an ordered list:

* indent zero spaces
* followed by a single digit
* followed by a period
* followed by a single space
* followed by text

Sublist items are indented sufficient to align with the beginning content of the parent (typically an additional three spaces, but more if you use multi-digit numbers).

Preferred due to ease of reordering items:

1. item 1
1. item 2
1. item 3
   1. item 1 of group 3

alternative:

1. item 1
2. item 2
3. item 3
   1. item 1 of group three

gotcha: this still renders as 1 2 3:

1. item 1
3. item 3
2. item 2

gotcha: this isn’t a sublist

1. item 1
1. item 2
1. item 3
  1. item 1 of group 3

tables.md

# per column alignment

| left        |   center    |       right | default (left aligned) |
|:------------|:-----------:|------------:|------------------------|
| lorem       |   lorem     |       lorem | lorem                  |
| lorem ipsum | lorem ipsum | lorem ipsum | lorem ipsum            |

(afaik: no way to apply alignment per cell)

text.md

## Emphasis

|       |                |
|-------|----------------|
| _foo_ | `<em>foo</em>` |
| *foo* | `<em>foo</em>` |

## Strong

|         |                        |
|---------|------------------------|
| __foo__ | `<strong>foo</strong>` |
| **foo** | `<strong>foo</strong>` |

## Strikethrough

|         |                  |
|---------|------------------|
| ~~foo~~ | `<del>foo</del>` |

## Blockquote

> this text is blockquoted

## Embedded HTML

The menu showed the option <samp>COMMAND</samp>.

Frequently Asked Questions (FAQs)

Why are they called “atx-style” headers?

In reference to Aaron Swartz’ atx format.

atx-style:

# h1

## h2

setext-style:

h1
==

h2
--

Further reading:

How do you add a caption to a table?

Captions are not supported.

What are the supported highlighter values?

Depends on your syntax highlighter plug-in. I use alecthomas/chroma whose README.md lists their supported languages.

Resources