HOWTO: Improve your use of Markdown in Discourse

Site Feedback
,
1

Introduction

Markdown is a way to apply HTML (web language) formatting to plain text in a quick and mostly intuitive way. It looks a bit like formatting used to look in plain text emails, for those who remember that!

The first thing to know about using Markdown in Discourse is that you don’t have to use Markdown to use Discourse! You can get by perfectly well by using the toolbar in the Composer in Discourse, or by reply-by-email.

What Markdown adds is the ability to quickly format your posts using plain text - yet in the Markdown preview bold, italic, preformatted text, strikethrough, and semantic headings. You can add links, images, tables and emoji as well using Markdown.

Markdown Basics

To get you started, here are the first few steps in Markdown that you might like to learn:

Bold text

To embolden some text, simply wrap it in double asterisks like this - **bold** which will render as bold.

Italic text

Using just one set of wrapping asterisks will result in italic text - *italic* which will render as italic.

Headings

Starting a line with # then a space, then some text, will give you a heading - the text is larger and emboldened too.

# H1 is the largest heading size, which will render as

H1 is the largest heading size.

Emoji

If you type a colon : and then start typing the name of the emoji you want, eg :smile_cat: this will bring up a mini-menu of emoji options, from which you can choose. Discourse autocompletes the ending colon for you and it renders like :smile_cat:.

Once you have got the hang of these initial Markdown features, you can consult the Markdown guide below to learn more.

Guides

There is a guide on the full Markdown specification here. Most of the CommonMark Markdown specification is implemented in Discourse:

There is a more detailed article on Markdown on the website of its creator, John Gruber:

And for serious Markdown geeks, you can read all about the origins and development of Markdown on Wikipedia:

Markdown hacks

Some things can be difficult to do in Markdown, such as underlined text, and
        arbitrary tab indentation, so here is a link to some hacks which can help you achieve these.

4 Likes