Teaching Kit

How to use Markdown

Markdown is an easy way to create human-readable text that converts to HTML. This is a brief tutorial demonstrating how to use it.

Original by @Tripad, this remix by @dajbelshaw

What is Markdown?

Markdown is a way of structuring a plain-text document so that it can be converted into HTML by a computer. It was created by John Gruber who says of it:

Readability... is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

An easy way to think of it is that Markdown is a human-centric way of composing something that will end up as a web page.

Where is Markdown used?

Markdown is often used as an option when creating blog posts. For example, you can create posts on Tumblr and Svbtle using Markdown - and using (self-hosted) WordPress if you use a plugin.

In the Webmaker world, Markdown is used in at least two places: the Kit Builder prototype and the Discourse discussion platform as part of Webmaker Training

Learning objectives

  • Be able to explain the basic syntax of Markdown
  • Create your first web page using Markdown

Let's get started!

The Basics

Markdown will help you create easy-to-read web pages that are subsequently easy to edit. Markdown syntax is converted seamlessly into semantically correct HTML. All you need to do is write your document as text, adding the necessary syntax where necessary. Where Markdown finds the special syntax, it will automatically convert it into HTML for you.

An Example

Look at how *awesome* [Markdown](http://daringfireball.net/projects/markdown/syntax) is, you can make text **bold** and
+ even
+ create
+ lists!
And check out this cat gif!
![Awesome cat gif](http://media.giphy.com/media/7z2oyDXIMEs8w/giphy.gif)

This would be rendered like this:

Look at how awesome Markdown is, you can make text bold and
  • even
  • create
  • lists!

And check out this cat gif!

Awesome cat gif

Markdown Syntax

Official guide

It's worth getting to know the official Markdown syntax page provided by John Gruber. It's useful when you end up going beyond what this brief tutorial covers!

Useful syntax

This should be enough to get you started:

Heading (H1): #H1 text here, ##H2 text here (etc.)

Italics: *italic text here*

Bold: **bold text here**

Link: [Linked text here](http://link_url.com/?test)

Blockquote: Quoted text

Unordered list:
+ list
+ text
+ here

Ordered list:
1. list
2. text
3. here

Image: ![My awesome image](http://link_url.com/image.jpg)

Some Tips:

  • If something isnt working..trying checking if you left some unwanted space between the syntax
  • Both '*' and '_' underscores can be used in both and italics
  • '+' , '*' or '-' can be used to generate unordered list
  • You can use artibrary HTML in Markdown. So if you write some Markdown, then some HTML, and then some Markdown, it will all render in HTML.

Document Released under :

Image attribution: CC BY-NC James Forsyth

Questions? Comments? The original author of this teaching kit is @_Tripad on Twitter and the remixer is @dajbelshaw!