A very, very, very short markdown tutorial

Site Feedback
#1

As of now, the new forum guidelines encourage people to use markdown. This has already been criticized as being too difficult or confusing, and even Troy said that he doesn’t like it. Since I actually do like it and think that it can be a very nice and tool to bring some structure to a post, I decided to give a very basic tutorial. I totally understand when people shy away from markdown when they have never used a markup language, though. That’s why I decided to keep it real short.

What is markdown?

Markdown is a markup language. The whole point of a markup language is to mix your text with commands, that tell the browser (or some other program) to format things in a certain way. In other words, you don’t format your document yourself while you write it, like you would in Microsoft Word. Instead, you just specify how you want it to be formatted. The actual formatting is done later by some rendering engine, in our case by the browser. For that reason, an approach like with Word is sometimes called WYSIWYG (What You See Is What You Get), while the markdown approach is called WYSIWYM (What You See Is What You Mean).

Let’s get to it.

Headers

Markdown let’s you write headers with up to six levels. For the highest level, write a single hashtag followed by a space followed by the actual heading:

# This is H1

comes out as:

This is H1

Likewise

## This is H2

comes out as:

This is H2

and just in case you didn’t guess it:

### this is H3

comes out as:

This is H3

If you need more levels, add more hashtags.

Horizontal Rulers

You can also add a horizontal ruler for separating stuff. Just write three (or more) asterisks in a row:

***

and it will look like this:

Lists

You can make a list of items like so:

- item 1
- item 2
- item 3

Which looks like this:

  • item 1
  • item 2
  • item 3

And lastly, you can have numbered lists, too:

1. number 1
2. number 2
3. number 3
  1. number 1
  2. number 2
  3. number 3

I hope that helps. Of course you can do more with markdown. If you are interested, just google it or look here. But in my opinion, this is all you need to structure a forum post. Feel free to ask, if you have any questions or comments!

4 Likes
#2

Hey, thanks for sharing, this is a good quick intro!

Haha I think I’ll end up removing that bit from the updated forum guidelines FYI, it’s indeed probably unnecessarily technical for most people’s needs, especially since the editor toolbar has the handful of most important functions (bold, italic, hyperlinks, lists) built in.

The basics are actually pretty simple and it’s used on some major sites (e.g. Reddit and Stack Exchange) as well as in various text editors, so I think worth a few minutes for anyone who writes a lot in places where it’s used. Though I agree with Troy no one should feel like they have to be familiar with Markdown syntax to use a forum!

For anyone whose interest is piqued, here’s another good resource; it has a similar “60 second primer” as well as further links to learn more: https://commonmark.org/

2 Likes