Markdown Syntax Cheatsheet

Markdown

Markdown makes editing easier and faster. It is faster to use markdown than having to reach for the mouse to format things, and even if one wants to use the mouse there are markdown editors that provide. Markdown is very portable and since it is in plain text can be used across a plethora of devices and interfaces. It is highly readable without hiding any detail.

What follows is a basic tutorial and cheat sheet. We use Markdown Extra in WordPress. There are a few additional shortcodes and suggestions that are not strictly Markdown but are part of the markup patterns we use on our websites, to keep them clean and easy to maintain.

Headers

Headers are hash marks/pound signs with a space after them. There are other ways of doing headers in markdown, but this is the way we like.

# = H1
## = H2
### = H3
etc.

Ordered Lists and Unordered Lists

Ordered lists simply can use numbers periods and spaces, as in:

1. First item
2. Second item

Unordered lists simply use a hyphen and a space as in:

- This item
- That item

Quote

A quotation is indicated by a greater than sign and a space as in: >. How that is formatted is up to the style sheets being used, but I prefer a margin of 15px around the quotation, slightly smaller or same font size, and possibly with a different background color. Some people make a quotation italic, though if it is long that just makes it unreadable. For multiline quotations, have the same greater-than sign in each paragraph mark, as in:

> My quotation
> 
> My second paragraph

Italic and Bold

Italic is any text surrounded by an asterisk * on either side. There must not be white space between the asterisks and the text, that is: *italic* and not * italic *.

Bold is any text surrounded by two asterisks ** on either side. As with Italic there must not be white space between the asterisks and the text, that is: **bold** and not ** bold **.

URLs

URLs are in the format [link text](https://domain.com/directory). Relative urls can be used if they are on the site where the content is being published (remove the domain part of the URL).

Note that for an email address, all that is needed are angle brackets, thus: <info@domain.com>.

Images

Images are in the format ![alt text](http://domain.com/directory/image.png "Optional Title"). Relative urls can be used if they are on the site where the content is being published (remove the domain part of the URL)

CSS Classes

One can apply CSS classes to headers, links and images. Simply add the class name as such after the item in question. {.class}. However for things like text one needs to use a <div> or a <p> and define the class inside the tag.

We have three classes defined for images -- .img-left, .img-right, .img-center. The first two classes, when used with 300px images allows for left or right alignment with appropriate margins. An image can be tagged as:

![My 300px image](/image/image.png "My 300px image title){.img-right}

The third class .img-center is meant for images that are the width of the display port, and will center and set the image to 99% width (cannot center with 100% width).

Centering Text and Images

Centering text and images requires using a <div> and a class or style, and that <div> must be marked as being processable by markdown (as markdown normally does not process what is inside of html). The only exception is for images which are already close to the width of the display port, in which case the .img-center can be used.

<div markdown="1">
markdown here
</div>

In CSS for our sites, there is the class center which is defined thus: .center{text-align:center;} and so centering text or images would use the following markdown:

<div class="center" markdown="1">
markdown here
</div>

Otherwise we can put the style directly in the <div>. Note that with this we can choose to text-align:right as well.

<div style="text-align:center;" markdown="1">
markdown here
</div>

Code and Preformatting

Using backticks `text` will create preformatted text. For so-called fenced code blocks we prefer the use of three tildes, then a return, then the code (which can be multiline), then another return and three more tildes, thus:

~~~
Fenced Code Block
~~~

yields

Fenced Code Block

To escape backticks, one needs another set of backticks (but incremented by one). To do the above display I needed two backticks, then a space, then the single backtick on either side of the text then another double backtick. I wrapped the tildes in backticks and some <br /> to show what I could.

Footnotes

Footnotes are as follows. Add a square bracket reference, and then after the paragraph break, add the same square bracket reference, a colon, and the footnote. Footnotes themselves can have paragraphs, as long as the second and subsequent paragraphs of the footnote are indented with four spaces.

That's some text with a footnote.[^1]
[^1]: And that's the footnote.

    That's the second paragraph.

You can use any footnote indicator, it doesn't have to be a number. Note also that the actual footnote does not have to go where the footnote is meant to be, it only has to go after the initial footnote reference mark. It will be placed where footnotes are meant to go automatically (usually the end of the page).

Horizontal Rule

There are a few ways to do this, but the most intuitive is four hyphens ---- with line breaks before and after.


Breaking Space and Line Breaks vs. End of Paragraph

In HTML this is a difference between a break <br /> and ending a paragraph </p>. In markdown having two spaces at the end of the line does perform a break. However in web pages this doesn't always translate, and so sometimes using a manual <br /> is needed when formatting something when a css style is not handy or reliably present. For example, dealing with signatures in HTML email.

Tables

This can be a bit twiddly, so keep the guide handy. It is possible to mark up tables and give them classes as well. An example:

Right | Left | Default | Center 
-----:|:-----|---------|:-----: 
  12  |   12 |      12 |    12 
  123 |  123 |     123 |   123 
    1 |    1 |       1 |     1

Yields

Right Left Default Center
12 12 12 12
123 123 123 123
1 1 1 1

CSS Accordion

Not actually markdown, but this is how we get a pure CSS accordion:

<details markdown="1">
<summary markdown="1">### Accordion - CSS Only</summary>
Text here
</details>

Thus

<details>
<summary><h3>Accordion - CSS Only</h3></summary>
<p>Text here</p>
</details>

HTML Entities and punctuation

It is wise to avoid HTML Entities and Unicode when possible. Of course when not possible, then don't. The main disadvantage is in search, as html entities and unicode are often not used in search, yet documents with those won't be returned. For example: &amp; is not the same thing as &.

Avoid things like &emdash; and &endash; and instead prefer good old double hyphens, or single hyphens (with spaces on either side). The main problem with there not being spaces between two words connected with a dash is that one cannot finely select one of the words by itself (try doing this in your ebook reader, impossible). Also, once again search and be confused and think it is a single thing: two words and their connecting dash.

Embedding Video and Audio

Again, not markdown, but part of WordPress functionality. Wrap the URL of a YouTube or Vimeo video in embed tags and it will be managed by our Video Lazyload plugin. Don't copy and paste more complicated embeds, just the straight URL. I find it difficult to escape these embed tags, but this is what it looks like (without all the white space in the tags):

[ embed ]full video url here[ / embed]

Voila