Updated 16-Aug-2024
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: ``.
Images
Images are in the format . 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 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 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 here
</div>
WordPress image srcset and other parameters
In Markdown Extra, class and other attributes can be set using curly-brackets. The Alt is set inside the square brackets. For the curly-brackets, there are no double quotes. This means that multiple class declarations must be set individually.
Example:
{width=620 height=223 class=alignnone class=size-full class=wp-image-22108}
This renders in WordPress as:
<img loading="lazy" src="/wp-content/uploads/sites/2/2021/04/Screenshot-from-2021-04-01-13-46-09.png" alt="Y7369 / R-S8958" width="620" height="223" class="alignnone">
Note that injecting the normal image HTML code is nearly identical to the markdown extra code, though with a bit more verbosity. WordPress takes care of the srcset responsive approach.
Another option, or used in addition, is to ensure that images being used are 300px in width and 250px in height. This also makes for useful images for the Google display network advertising.
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>
<summary>### 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: & 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