How to Use Markdown

WIRED

01-07-2025

When writing on the web or posting in online communities like Reddit and Discord, your posts can be formatted using the plaintext coding system called Markdown. Here are the basics. Illustration: Jacqui VanLiew
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*
text, put an asterisk before and after it, *like this* To bold text, put two asterisks before and after it, **like this**
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.
And, finally, there's speed. I personally find writing in Markdown a lot faster. I've used it for thousands of articles published online at many publications, including the one you're reading now. As I write, I appreciate that I can do all of my formatting without using menus and toolbars, and without even moving my fingers from the keyboard. As an editor, I appreciate knowing exactly where formatting begins and ends.
You can argue whether this is worth the trade-offs of the more familiar WYSIWYG editor, and many people have. But for many, myself included, Markdown is simpler to use while writing for the web. Apps and Resources
This article is intended as an introduction to Markdown, not a full guide. If you want to learn more, I highly recommend checking out MarkdownGuide.org, a website that takes the time to walk you through how Markdown works and why you might want to use it.
The real fun, though, comes when you start playing with Markdown editors. I mentioned MarkdownLivePreview.com, and that's a great starting point. There are also excellent editors for your computer. Typora is a very nice $15 application that lets you type in Markdown and see the formatting in real time. The very popular (and free) note-taking application Obsidian, which I personally use for writing and productivity, works the same way but with a lot more bells and whistles. Or, if you want something simple for editing single files, Markedit is quite good on the Mac, and MarkDownPad works well on Windows.
Learning Markdown is a bit of work up front, granted, but it can really speed up writing once you get used to it—and the right tools make it easier.