Markdown is probably the easiest markup language you'll ever learn. It was designed to be readable as plain text before you even render it. This guide walks through everything you need to know, from absolute basics to some of the more useful advanced features.
What Is Markdown?
Markdown is a way to format text using plain characters. Instead of clicking a "bold" button, you wrap text in double asterisks. Instead of selecting a heading style from a dropdown, you put a hash symbol at the start of a line. It was created by John Gruber and Aaron Swartz back in 2004 and it's become the standard for writing on the web.
If you've ever written a Reddit comment, formatted a README on GitHub, or posted in a Discord channel, you've probably used markdown already without realizing it.
Getting Started — The Basics
Open any markdown editor — I'll use MDtoTEXT here because it shows a live preview as you type, which is helpful when you're learning. Type these examples and watch them render.
Headings
Use the # symbol. One # is the biggest heading (H1), two ## is slightly smaller (H2), and so on down to ###### (H6).
# This is a Heading 1 ## This is Heading 2 ### Heading 3 #### Heading 4
A good rule: use one H1 per page (treat it like the page title), and don't skip levels. Don't go from H2 to H4 — something in between should be H3.
Bold and Italic
Wrap text in asterisks or underscores:
**bold text** or __bold text__ *italic text* or _italic text_ ***bold and italic***
Double asterisks are bold, single is italic, triple is both. I prefer asterisks over underscores — they're easier to spot in plain text.
Links
The syntax is square brackets for the display text, followed by parentheses for the URL:
[Click here](https://example.com)
You can also add a title attribute that shows up on hover:
[Click here](https://example.com "Optional title")
Images
Same as links but with an exclamation mark at the front:
The alt text is important for accessibility and shows up if the image fails to load.
Lists
Unordered lists use dashes, asterisks, or plus signs:
- Item one - Item two - Nested item (indent with two spaces)
Ordered lists use numbers:
1. First item 2. Second item 3. Third item
The actual numbers don't matter — you can use all 1's and markdown will render them in order. But I use sequential numbers for clarity when reading the source.
Blockquotes
> This is a quoted line > This is also quoted > > You can have multiple paragraphs too
Code
For inline code (like variable names or short commands), use single backticks:
Use the printf() function to print text.
For code blocks, use triple backticks. Optionally specify the language for syntax highlighting:
```python
def hello():
print("Hello, world!")
```
Horizontal Rules
Three or more dashes, asterisks, or underscores on their own line:
--- ***
Intermediate Features
Tables
Tables are a bit clunky in markdown but they work:
| Name | Age | Role | |------|-----|------| | Alice | 30 | Admin | | Bob | 25 | Editor | | Carol | 28 | Viewer |
The dashes separate the header from the body. The colons control alignment — :--- is left, ---: is right, :---: is center.
Task Lists
- [x] Completed task - [ ] Incomplete task
Footnotes
Here's some text with a footnote[^1]. [^1]: And here is the footnote itself.
Strikethrough
~~This text is crossed out~~
Advanced: Diagrams and Math
Some markdown editors support extra features. MDtoTEXT supports Mermaid diagrams and LaTeX math, which are incredibly useful for technical writing.
Mermaid Diagrams
Write flowcharts, sequence diagrams, and Gantt charts using plain text:
```mermaid
graph LR
A[Start] --> B{Decision}
B -->|Yes| C[Continue]
B -->|No| D[Stop]
```
LaTeX Math
For inline math, wrap in single dollar signs: $E = mc^2$
For display math, use double dollar signs:
$$ \sum_{n=1}^{10} n^2 $$
Practical Tips
Here's advice I wish someone gave me when I started:
1. Add a blank line before headings and after them. It makes the source much more readable.
2. Use a live preview editor while you're learning. Seeing the rendered output alongside your source helps you understand what each syntax element does. MDtoTEXT works great for this.
3. Don't memorize everything. Bookmark a cheat sheet. After a week of regular use, the common syntax becomes automatic.
4. Markdown files are just plain text files with .md extension. You can edit them in any text editor, even Notepad. But a dedicated editor with preview is a lot more comfortable.
What's Next
Once you've got the basics down, you can write just about anything. Documentation, blog posts, notes, emails, even books. The MDtoTEXT documentation covers all the features in detail. Or just open the editor and start typing — that's the best way to learn.