Markdown Cheatsheet

12 mins read.

Quick reference guide for writing with markdown on this blog (maybe, even in others).

This was taken from adam-p/markdown-here and it was slightly modified for its use on this blog.

  • Mostly, this document describes syntax rules compatible with GFM, Markdown-here and kramdown, so you can safely use them on your READMEs, to write your documentation and convert it to another format, and sometimes even to style your comments.
  • An annex describes rules exclusive to kramdown(which is used here) that add a nice plus when writing for the web.

While reading this or any other markdown guide, you will notice that there are elements that can be described in more that one way (e.g list, emphasis, links). My personal advice is to choose an style and stick with it for the rest of your document, maybe even for all of your documents.

Although the renderer won’t have problems if you decide to mix them in your documents, it’ll cause difficulties when trying reading the plain document, either to update it or to fix an error. It will also complicate things if you decide to collaborate and you have to share your plain documents.

Headers

# H1
## H2
### H3
#### H4
##### H5
###### H6

H1

H2

H3

H4

H5
H6

Emphasis

Emphasis, aka italics, with *asterisks* or _underscores_.

Strong emphasis, aka bold, with **asterisks** or __underscores__.

Combined emphasis with **asterisks and _underscores_**.

Strikethrough uses two tildes. ~~Scratch this.~~

Emphasis, aka italics, with asterisks or underscores.

Strong emphasis, aka bold, with asterisks or underscores.

Combined emphasis with asterisks and underscores.

Strikethrough uses two tildes. Scratch this.

Lists

1. First ordered list item
2. Another item
  - Unordered sub-list
1. Actual numbers don't matter, just that it's a number
  1. Ordered sub-list
4. And another item

   You can have properly indented paragraphs within list items. Notice the blank
   line above, and the leading spaces (at least one, but we'll use three here to
       also align the raw Markdown).

   To Have a line break without a paragraph, you will need to use two trailing
   space.  Note that this line is separate, but within the same paragraph.  

* Unordered list can use asterisk
- Or minuses
+ Or pluses
  1. First ordered list item
  2. Another item
    • Unordered sub-list
  3. Actual numbers don’t matter, just that it’s a number
  4. Ordered sub-list

  5. And another item

    You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least three).

    To Have a line break without a paragraph, you will need to use two trailing space. Note that this line is separate, but within the same paragraph.

  • Unordered list can use asterisk
  • Or minuses
  • Or pluses
There are two ways to create links.

[I'm an inline-style link](https://www.duckduckgo.com)

[I'm an inline-style link with title](https://www.duckduckgo.com "DuckDuckGo's Homepage")

[I'm a reference-style link][Securing your github pages with HTTPS]

[I'm a relative reference to a repository file](../blob/master/LICENSE)

[You can use numbers for reference-style link definitions][1]

Or leave it empty and use the [link text itself].

URLs and URLs in angle brackets will automatically get turned into links. 
<https://www.example.com>

Some text to show that the reference links can follow later.

<!-- The link references will not be rendered on the document -->  
[securing your github pages with https]: https://help.github.com/articles/securing-your-github-pages-site-with-https/ "Securing your GitHub Pages site with HTTPS"
[1]: https://slashdot.org
[link text itself]: https://www.reddit.com

There are two ways to create links.

I’m an inline-style link

I’m an inline-style link with title

I’m a reference-style link

I’m a relative reference to a repository file

You can use numbers for reference-style link definitions

Or leave it empty and use the link text itself.

URLs and URLs in angle brackets will automatically get turned into links. https://www.example.com

Some text to show that the reference links can follow later.

Images

Here's my logo (hover to see the title text):

Inline-style: 
![XolotlP](/assets/site-logo.png "XolotlP's Page Logo"){:height="24px" 
  style="display: inline"}

Reference-style: 
![XolotlP][logo]{:height="24px" style="display: inline"}

[logo]: /assets/site-logo.png "XolotlP's Page Logo"

Here’s my logo (hover to see the title text):

Inline-style: XolotlP

Reference-style: XolotlP

Code and Syntax Highlight

Code blocks are part of the Markdown spec, but syntax highlighting isn’t. However, many renderers – like GitHub’s and kramdown – support syntax highlighting. Which languages are supported and how those language names should be written will vary from renderer to renderer.

Inline `code` has `back-ticks around` it.

Inline code has back-ticks around it.

There are two types of code blocks fenced and indented:

  • Fenced code blocks are surrounded by lines with at least three back-ticks ```, or at least three tildes ~~~.
    The line with the opening code fence may optionally be followed by an info string used to specify the language of the code sample (useful for syntax highlight).
  • Indented code blocks are indented chunks surrounded by blank lines, where each line is indented by 4 or more spaces.
``` javascript
var s = "JavaScript syntax highlighting";
alert(s);
```
 
``` python
s = "Python syntax highlighting"
print s
```
 
```
No language indicated, so no syntax highlighting. 
But let's throw in a <b>tag</b>.
```

var s = "JavaScript syntax highlighting";
alert(s);

s = "Python syntax highlighting"
print s

No language indicated, so no syntax highlighting. 
But let's throw in a <b>tag</b>.

Tables

Tables aren’t part of the core Markdown spec, but they are part of GFM and kramdown supports them. They are an easy way of adding tables to your email – a task that would otherwise require copy-pasting from another application.

Colons can be used to align columns.

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| col 3 is      | right-aligned | $1600 |
| col 2 is      | centered      |   $12 |
| zebra stripes | are neat      |    $1 |

There must be at least 3 dashes separating each header cell.
The outer pipes (|) are optional, and you don't need to make the 
raw Markdown line up prettily. You can also use inline Markdown.

Markdown | Less | Pretty
--- | --- | ---
*Still* | `renders` | **nicely**
1 | 2 | 3

Colons can be used to align columns.

Tables Are Cool
col 3 is right-aligned $1600
col 2 is centered $12
zebra stripes are neat $1

There must be at least 3 dashes separating each header cell. The outer pipes (|) are optional, and you don’t need to make the raw Markdown line up pretty. You can also use inline Markdown.

Markdown Less Pretty
Still renders nicely
1 2 3

Blockquotes

> Blockquotes are very handy in email to emulate reply text.
> This line is part of the same quote.

Quote break.

> This is a very long line that will still be quoted properly when it wraps. Oh
> boy let's keep writing to make sure this is long enough to actually wrap for
> everyone. Oh, you can *put* **Markdown** into a blockquote.

Blockquotes are very handy in email to emulate reply text. This line is part of the same quote.

Quote break.

This is a very long line that will still be quoted properly when it wraps. Oh boy let’s keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can put Markdown into a blockquote.

HTML Elements

You can also use raw HTML in your Markdown, and it’ll mostly work pretty well.

<dl>
  <dt>Definition list</dt>
  <dd>Is something people use sometimes.</dd>

  <dt>Markdown in HTML</dt>
  <dd>Does *not* work **very** well. Use HTML <em>tags</em>.</dd>
</dl>
Definition list
Is something people use sometimes.
Markdown in HTML
Does *not* work **very** well. Use HTML tags.

This is really useful when you require some really complicated description of an element or when markdown’s syntax rules are in conflict with the kind of element you want to describe.

For example to show ```, you can’t surround them with simple ` as it will look like ````` and will not be correctly interpreted, and surrounding them with ~ doesn’t work on inline code blocks, then your only option is to use the <code> tag and the html reference $#96;.

Horizontal Rule

To add an horizontal rule you can use three or more:

  • --- hyphens
  • *** asterisk
  • ___ underscores

Make sure there is an empty line before your horizontal rule declaration

Three or more...

---

Hyphens

Three or more…

Hyphens

(Note: depending on your editor certain markers can break your syntax highlight, e.g on my vim when I use *** or ___ the following text is highlighted as if I was trying to use ** or __, even though the document is correctly rendered)

Line Breaks

To start a new line without start a new paragraph, end your line with two trailing spaces. GFM also supports breaking lines with \ and kramdown with \\, but if you plan to share your markdown documents across different platforms is safer to use trailing spaces as is more standard-ish.

Here's a line for us to start with.

This line is separated from the one above by two newlines, so it will be a
*separate paragraph*.

This line is also a separate paragraph, but...
This line is only separated by a single newline, so it's a separate line in the 
*same paragraph*.

Here’s a line for us to start with.

This line is separated from the one above by two newlines, so it will be a separate paragraph.

This line is also a separate paragraph, but…
This line is only separated by a single newline, so it’s a separate line in the same paragraph.

YouTube Videos

They can’t be added directly but you can add an image with a link to the video like this:

<a href="https://www.youtube.com/watch?v=[VIDEO-ID]" target="_blank">
  <img src="https://img.youtube.com/vi/[VIDEO-ID]/0.jpg"
  alt="Video Title" width="240"/>
</a>

Or, in pure Markdown, but losing the image sizing:

[![Video Title](https://img.youtube.com/vi/[VIDEO-ID]/0.jpg)](https://www.youtube.com/watch?v=[VIDEO-ID])

Video Title

Or, in pure Markdown, but losing the image sizing:

Video Title

kramdown

Footnotes

One of my favorite elements that I consider necessary to read and write without disrupting the flow. Just set a footnote marker (consists of square brackets with a caret and the footnote name inside) in the text and somewhere else the footnote definition (which basically looks like a reference link definition):

This is a text with a
footnote[^1].

[^1]: And here is the definition.

This is a text with a footnote1.

Definition Lists

Definition lists are started when some text is followed by a new line starting with a colon and then the definition text. One term can have many definitions and multiple terms can have the same definition.

Term
: definition
: another definition

Another term
and another term
: and a definition for the term
Term
definition
another definition
Another term
and another term
and a definition for the term

Block IALs and ADLs

Sometimes you want a block item to have certain attribute, a class or an id, and you can’t or don’t want to use html elements, you can directly follow the element with a block inline attribute list (block IAL), which consist of a colon :, followed by the attribute definitions (same as in HTML), all enclosed in curly braces.

> A nice blockquote
{: title="Blockquote title"}

A nice blockquote

Classes and IDs have a nice shortcut

> A nice blockquote
{: .class1 #with-an-id }

A nice blockquote

And sometimes you want to use the same attributes for many elements. kramdown allows you to define the attributes in one place with an attribute list definition (ADL) and just reference this definition in a block IAL.

{:refdef: .c1 #id .c2 title="title"}
some text
{: refdef}

some text

More elements

kramdown has other elements that I don’t use for this blog, so if you are interested in all that kramdown can offer to you, I recommend reading its official documentation.

License: CC-BY

  1. And here is the definition. ↩