Markdown - using it to make your posts awesome

Overview

Markdown is utilised by spokes.nz (and other sites based on the Discourse platform) to allow simple text responses as well as richly formatted web content within a single composer. Here is a ‘Cheat Sheet’ which gives you a quick look at all the important stuff:

Markdown 101

The most useful things are entering text, headings, the formatting bar, and numbers/bullets for lists.

Entering text

Type! All you have to do is type some text and it appears just like that. Dead simple.

Do be aware that it will automatically remove any redundant spaces / lines.

Headings

To utilise headings, simply drop a hash # in front of the text of the heading with a space after it. For example,

### Three hashes give you a 3rd level heading
#### Four hashes give you a 4th level heading
#### Five hashes give you a 5th level heading

like this:

Three hashes give you a 3rd level heading

Four hashes give you a 4th level heading

Five hashes give you a 5th level heading

As you can see, the more hashes, the deeper (smaller) the heading. In this page, Overview, Markdown 101, and More Information are single # headings. Entering text, Headings, and The formatting bar are double ## headings (2nd level).

When using Tables of Content

You can add a Table of Content (TOC) to your post via the gear icon on the composer bar (see below). This is automatic when an Original Post is a wiki (like this one).

This TOC is automatically generated from your headings, and is excellent for long and complex posts (like this one).

The formatting bar

I mean this:

image

If you highlight the relevant text and click the buttons, the correct Markdown will replace your simple text in the composer. Most are pretty obvious and explain themselves when you hover over them.

quote The quotation

This highlights the text as I’ve done for the formatting bar above, putting it in a little indented box that indicates it is more / different than the surrounding text. It does this by simply putting a > in front of every line that is included:

This is a quotation

:gear: The gear

The gear reveals a whole heap of extended functionality.

Numbered / Bulleted lists

These are super helpful:

  1. They allow you to make a series of clear points

  2. They automatically renumber themselves

    • You can use Bullets too
      • and you can indent them with some spaces

To make one, highlight a few lines and hit the relevant list button under the gear icon.

To do it directly in the composer, simply put a number with a dot (i.e. 1.) or an asterix * and a space at the start of a line like this:

1. They allow you to make a series of clear points

1. They automatically renumber themselves
   * You can use Bullets too
     * and you can indent them with some spaces

As you can see from the example above, adding two more spaces makes them indent. You can do that ad nauseam.

More Information

You might like to edit this wiki post and take a look at the Markdown used here.

Wikipedia gives an excellent overview:

For more detailed information you might find this interesting: