What it is
Markdown is the simple syntax used for writing blog posts & pages in plain text in such a way as when uploaded to the site, the file has rich formatting, links, images & more.
This guide will show the syntax and appearance of all Markdown elements, first with the Markdown syntax,
In a block like this,
Then show how that would appear on the webpage,
In a block like this.
A quick note on writing posts
All of the posts on this site need to be placed in the _posts folder and named using
the convention YYYY-MM-DD-Post-Name.md. The .md file extension means that this is a Markdown
file. Inside of that file, at the top of the document it is a requirement to have a
section like this:
---
title: Post Title (Doesn't have to match the filename title)
layout: post
---
Don’t change the layout: post option unless you wish to use a different layout (They’re in the
_layouts folder) which is highly unlikely and rarely necessary.
This section of the post is not Markdown so may confuse a third party application and render weirdly, showing a horizontal rule and treating the last line as a heading.
Typography
Headings
The main headings you’ll use, h1 & h2 use this syntax:
Heading 1
=========
Heading 2
---------
Which shows on the page as:
Heading 1
Heading 2
They can also follow the alternate syntax:
Headings from h1 through h6 can be written with a # for each level of heading:
# h1 Heading
## h2 Heading
### h3 Heading
#### h4 Heading
##### h5 Heading
###### h6 Heading
Note that anything past h4 has little use. These look like this in the final web page:
h1 Heading
h2 Heading
h3 Heading
h4 Heading
h5 Heading
h6 Heading
Body Copy (Paragraphs)
Body copy written as normal, plain text will be formed into paragraphs on the web page.
Note that to start a new paragraph you need to leave a line, and that you can put single
line breaks in anywhere without affecting the formatting. Note ...mandamus. Et legere ...
So this body copy in Markdown:
Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus.
Et legere ocurreret pri, animal tacimates complectitur ad cum.
Cu eum inermis inimicus efficiendi. Labore officiis
his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
Class aptent taciti sociosqu ad litora torquent per conubia nostra,
per inceptos himenaeos. Nullam ut molestie arcu. Cras vitae arcu non
metus facilisis hendrerit.
Will look like:
Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.
Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Nullam ut molestie arcu. Cras vitae arcu non metus facilisis hendrerit.
Emphasis
Bold
For emphasizing a snippet of text with a heavier font-weight.
The following snippet of text is rendered as bold text.
**this is bold text in Markdown**
Will appear as:
this is as bold text in Markdown
Italics
For emphasizing a snippet of text with italics.
The following snippet of text is rendered as italicized text.
_rendered as italicized text_
Appears as:
rendered as italicized text
Stylistic Elements
Lists
Unordered (Bullet Points)
A list of items in which the order of the items does not explicitly matter.
You may use any of the following symbols to denote bullets for each list item:
* valid bullet
- valid bullet
+ valid bullet
For example
+ Lorem ipsum dolor sit amet
+ Consectetur adipiscing elit
+ Integer molestie lorem at massa
+ Facilisis in pretium nisl aliquet
+ Nulla volutpat aliquam velit
- Phasellus iaculis neque
- Purus sodales ultricies
- Vestibulum laoreet porttitor sem
- Ac tristique libero volutpat at
+ Faucibus porta lacus fringilla vel
+ Aenean sit amet erat nunc
+ Eget porttitor lorem
Will get nicely displayed as:
- Lorem ipsum dolor sit amet
- Consectetur adipiscing elit
- Integer molestie lorem at massa
- Facilisis in pretium nisl aliquet
- Nulla volutpat aliquam velit
- Phasellus iaculis neque
- Purus sodales ultricies
- Vestibulum laoreet porttitor sem
- Ac tristique libero volutpat at
- Faucibus porta lacus fringilla vel
- Aenean sit amet erat nunc
- Eget porttitor lorem
Ordered (Numbered Lists)
A list of items in which the order of items does explicitly matter. Be careful to ensure that the indentation of nested lists is the same as the indentation of the text above it
1. Lorem ipsum dolor sit amet
2. Consectetur adipiscing elit
1. Integer molestie lorem at massa
2. Facilisis in pretium nisl aliquet
3. Nulla volutpat aliquam velit
3. Faucibus porta lacus fringilla vel
4. Aenean sit amet erat nunc
5. Eget porttitor lorem
Again becomes:
- Lorem ipsum dolor sit amet
- Consectetur adipiscing elit
- Integer molestie lorem at massa
- Facilisis in pretium nisl aliquet
- Nulla volutpat aliquam velit
- Faucibus porta lacus fringilla vel
- Aenean sit amet erat nunc
- Eget porttitor lorem
PROTIP: If you just use 1. for each number, the end product will still be a correctly
numbered list. For example:
1. Lorem ipsum dolor sit amet
1. Consectetur adipiscing elit
1. Integer molestie lorem at massa
1. Facilisis in pretium nisl aliquet
1. Nulla volutpat aliquam velit
1. Faucibus porta lacus fringilla vel
1. Aenean sit amet erat nunc
1. Eget porttitor lorem
Will get wonderfully fixed for you like this:
- Lorem ipsum dolor sit amet
- Consectetur adipiscing elit
- Integer molestie lorem at massa
- Facilisis in pretium nisl aliquet
- Nulla volutpat aliquam velit
- Faucibus porta lacus fringilla vel
- Aenean sit amet erat nunc
- Eget porttitor lorem
Tables
Tables can be a bit of a formatting nightmare, so use them sparingly. There’s a compromise
between the complexity of the Markdown syntax and the features, so there aren’t many options here.
Note that the line of |---|---|---| etc. is optional and makes the row above a header.
| First cell | Second cell | Third cell |
|------------|-------------|------------|
| First | Second | Third |
| First | Second | Third |
Will get turned into:
| First cell | Second cell | Third cell |
|---|---|---|
| First | Second | Third |
| First | Second | Third |
You can also affect the indentation of table columns with some slightly tricky syntax:
| Tables | Are | Cool |
| ------------- |:-------------:| -----:|
| col 3 is | right-aligned | £1600 |
| col 2 is | centered | £12 |
| zebra stripes | are neat | £1 |
Adding colons in the place of a - will either centre the text in that column or right-align it, based on whether you use :-----: or ------:. The above example looks like this:
| Tables | Are | Cool |
|---|---|---|
| col 3 is | right-aligned | £1600 |
| col 2 is | centered | £12 |
| zebra stripes | are neat | £1 |
Links
Basic link
[Google UK](https://google.co.uk)
Will show up as
Linking to stuff on your site
There’s a more futureproof way of linking to your own content.
[Awesome Post]({% post-url 2014-10-20-name-of-post %})
This is shown as:
As long as the 2014-10-20-name-of-post part matches the filename of the post you’re linking
to (notice the lack of a .md extension) this will work. Also if it isn’t, the site won’t update,
which is bad
Add a title to a link
[Google UK](https://google.co.uk "Visit Google UK")
Comes out as this: (hover over the link, there should be a tooltip)
Footnote Links
Instead of placing the URL next to the link like [Link Name](http://website.com) you can instead
place an identifying name next to the link, as shown below. This method still supports titles.
[Google UK][google]
... You can put anything in here ...
[google]: https://www.google.co.uk "Go to Google UK"
Like so:
Images
Images have a similar syntax to links but start with an exclamation point.
Gets shown as:
In the same way as images, you can add alternate text that will show if the image fails to load. (Doing this is recommended by the people who invented the Web)
Again gets shown as:
Like links, Images also have a footnote style syntax for adding the URL later on in the document.
![Alt text][id]
With a reference later in the document defining the URL location. Note that the reference is invisible.
[id]: http://octodex.github.com/images/dojocat.jpg "The Dojocat"
Horizontal Rules
The HTML <hr> element is for creating a “thematic break” between paragraph-level elements.
In Markdown, you can create a <hr> with any of the following in your Markdown document:
___: three consecutive underscores---: three consecutive dashes***: three consecutive asterisks
Any of these would look like:
Block Quotes
For quoting blocks of content from another source within your document.
Add > before any text you want to quote.
> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.
Will show up as:
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Integer posuere erat a ante.
Blockquotes can also be nested:
> This is a paragraph.
>
> > A nested blockquote, i.e. a blockquote inside a blockquote.
>
> ## Headers work
>
> * lists too
>
> and all other block-level elements
> <cite>Unfortunately, if you need a citation, that's a HTML thing</cite>
Shows on the page as:
This is a paragraph.
A nested blockquote, i.e. a blockquote inside a blockquote.
Headers work
- lists too
and all other block-level elements Unfortunately, if you need a citation, that’s a HTML thing
Monospaced text & Code
Inline monospace
Wrap inline snippets of code with `. That’s the funny backtick character in the bottom
left of the keyboard next to z (On a Mac).
So this:
For example, `<section></section>` should be wrapped as "inline".
Becomes this:
For example, <section></section> should be wrapped as “inline” and formatted.
Monospaced blocks.
This preserves the line breaks & indentation of your text, as well as changing the font to monospace. You’ll notice these are heavily used on this page to show syntax.
Adding four spaces to the start of a line, like this:
// Some comments
line 1 of code
line 2 of code
line 3 of code
Does this:
// Some comments
line 1 of code
line 2 of code
line 3 of code
Alternately
Use “fences” ~~~ to block in multiple lines of code.
~~~
This is a monospace block that doesn't need to have 4 spaces in front of it
~~~
Comes out of the wash appearing like this:
This is a monospace block that doesn't need to have 4 spaces in front of it
PRO - Markdown inside HTML
Just a word of warning - This is not easy, but will result in some pretty cool looking posts.
There are two parts to getting content into HTML whilst writing in Markdown. You have to first
capture your content in an object, by using the Liquid capture tags:-
{% capture unique_name %} …Markdown here…
{% endcapture %} and then pull that object into HTML where you want it to
appear, with the {{ unique_name | markdownify }} Liquid tag.
So, for example:
{% capture jumbo %}
Heading
=======
Paragraphs, and basically any other Markdown you can think of.
{% endcapture %}
<div class="jumbotron">
{{ jumbo | markdownify }}
</div>
will get rendered out as:
Heading
Paragraphs, and basically any other Markdown you can think of.
Note that the jumbotron class on the HTML <div> is an included
Bootstrap class. See that link for more formatting options.
Also, the name jumbo used in the capture must be the only capture called jumbo in the document.
You can re-use any data that you capture multiple times in the document. Liquid can do a lot, lot more
so check out the Jekyll documentation for more information.