How to Use Markdown | WIRED

Whether you’re posting on Reddit, Discord, or Github, there’s only one way to add formatting: Markdown. If you want to add a link, bold some text, or even split text into paragraphs, you will need to know the basics of this text-based formatting system.

Does that sound scary? Trust me, it’s not. Markdown has just a few rules for formatting text the way you want, and you only need to learn the rules for the formatting you actually use.

Let’s go over the simple rules, talk about why Markdown is useful, then take a look at a few resources you can use to go further with Markdown.

The Basics of Markdown

Markdown is a way to apply rich formatting to plaintext by adding certain characters to it. On platforms like Discord or Reddit, where messages are short and relatively simple, you really only need to learn a few basics:

• To italicize text, put an asterisk before and after it, *like this*
• To bold text, put two asterisks before and after it, **like this**
• To include a link, put the text of the link in square brackets followed immediately by the URL in parentheses, [Like this](https://justinpot.com/)
• To add an image, start with an exclamation point, with the square bracket containing a description of the image, and the parentheses containing a link to an image file, 
• To start a new paragraph, hit Enter twice, so that there’s a clear line between the current line of text and the next one.

The above five tips are more than enough for things like Reddit and Discord. Even though you’re typing what looks like code, when your post is published, all you’ll see is the rich-text formatting, complete with links and images.

If you’re using Markdown to write entire documents, though, you’re going to need a few document-specific tools. Here are the key ones:

• To make a header (like the large-font text “The Basics of Markdown” seen above on this article) start a line of text with a pound sign followed by a space, # Like this.
• To make smaller headers, use more pound signs, ## Like this for h2 or ### Like this for h3, and so on. The more pound signs you add, the smaller your header text will be.
• To create a bulleted list, simply start a line of text with an asterisk followed by a space, * Like this. You can add as many bulleted lines to your list as you want.
• To indent a list item, put a tab before the asterisk. To indent further, simply add more tabs.
• To create a numbered list, start a line of text with a number and a period, 1. Like this.
• To indent a numbered list item, add a tab before the number. To indent further, simply add more tabs.
• To add a block quote to your document, simply start a link of text with a “greater than” sign, > like this.

That covers most of what you need to know in order to write a document in Markdown. If you’re confused about how this formatting will look, it helps to play around and see the results. A great website to do this on is MarkdownLivePreview.com. The left panel shows the Markdown while the right side shows how that will look. Try different things there for a bit and you’ll feel a lot more comfortable.

Why Use Markdown at All?

This all might have you asking: Why are sites forcing people to learn a slightly esoteric way to format text? And the answer is that this system, even if a little bit confusing at first, is very straightforward and clear once you get used to it.

Most people get used to writing on a computer using tools like Microsoft Word or Google Docs. There are both word processors, meaning they are built to represent a printed page on your screen. They also both are called “what you see is what you get” editors—or WYSIWYG editors—meaning that the formatting is shown on the screen directly. If you bold some text, you see it as bold on the screen; if you add a link, you see the linked text get underlined and turn blue like it would on a web page. There is no way to tell, by looking at the text itself, where bolding begins and ends or what the destination of the link is.

This might seem intuitive, and to be fair there is a simplicity to it. But that simplicity is made possible by code that the user does not see, and the fact that the code is kept behind the scenes can be confusing in some ways. Anyone who has tried to add a few words to the end of a link, or right after a link, knows that this ambiguity can be frustrating—you’ll end up either accidentally making the link longer than you intended, or doing the opposite and adding text that’s not linked. This doesn’t happen while writing in Markdown because you can clearly see where all the formatting begins and ends.

Markdown files are also future-proof. Because all of the text formatting, linking, and document structure schema is written in plaintext, a format that hasn’t changed in decades and isn’t owned by any one company, you can be reasonably certain that anyone who finds a Markdown file in 50 years is going to be able to make sense of it. The same can’t be said about Microsoft Office files.