Markdown Basics
Learn markdown in ten minutes: headings, bold, links, lists, code, tables, frontmatter. The complete beginner's guide with examples.
Markdown Basics
Markdown is a lightweight markup language with plain text formatting syntax. It is easy to use and deployed all over the web – GitHub, Reddit, Stack Overflow, and everywhere else.
In Markdown you control the display of the document: formatting words as bold or italic, adding images, and creating lists are just a few of the things you can do. Mostly, Markdown is just regular text with a few non-alphabetic characters thrown in, like ## or **.
Why plain text?
First, plain text is awesome 😎 Plain text never goes out of fashion – plain text files written thirty years ago are still readable on your modern computer (unlike more complex formats). You can also create and use plain text almost anywhere.
But… plain text has no formatting like bold, italic, or bullet lists etc. Plain text needs conventions for "headings", lists, etc. Wouldn't it be cool if we had a way to add this to plain text and this then could be converted to HTML or something that does actually look good? Enter Markdown. 🦸
Learn by doing
Try it right now: our markdown playground – type on the left, see it rendered on the right, nothing to install 🎮
Prefer structured exercises? markdowntutorial.com and the CommonMark tutorial are both good.
The syntax
Text basics
usual text usual text
*italic text* italic text
**bold text** bold text
~~crossed through~~ crossed through
--- on its own line gives a horizontal rule:
To force a line break, end a line with two spaces.
Headings
# Heading 1
## Heading 2
### Heading 3 (and so on to 6)
One # Heading 1 per page, at the top, is the usual convention.
Links and images
https://example.com – bare URLs auto-link in most tools
[link text](https://example.com) – a proper link
 – an image (the ! in front is the difference)
Many markdown tools (Obsidian, Flowershow, wikis) also support [[wiki-links]]: double brackets around a page name links to that page. Not part of core markdown, but everywhere in knowledge-base land.
Lists
- item 1
- item 2
- item 2a (indent two spaces to nest)
1. first
2. second
- item 1
- item 2
- item 2a
Task lists (GitHub, Obsidian and friends – not everywhere):
- [ ] not done yet
- [x] done
Quotes
Santa Claus said:
> Happy Christmas, hohoho
Santa Claus said:
Happy Christmas, hohoho
Code
Inline code goes in single backticks: `like this`.
Multi-line code goes between triple-backtick lines, and you can name the language for syntax highlighting:
```python
print('hello world')
```
Renders as:
print('hello world')
Tables
| Name | Awesome? |
|------|----------|
| Markdown | Yes |
| .docx | No |
| Name | Awesome? |
|---|---|
| Markdown | Yes |
| .docx | No |
Advanced features
Formatting text with Markdown is as easy as using Notepad, and the syntax extends easily. Some extras worth knowing:
These aren't always supported – check your tool before relying on them.
Frontmatter
Frontmatter is metadata at the top of a file, between two --- lines:
---
title: 5 minute markdown guide
date: 2026-07-18
author: Rufus
---
Tools use it for page titles, dates, and anything else – it's also how markdown files act like database records.
Callouts
> [!info]
> My important message here.
My important message here.
Several types exist (info, warning, tip…) – see the Flowershow syntax docs for the full set.
HTML
And the escape hatch for everything else: plain HTML is valid markdown. If the syntax can't do it, <html> can – this matters more than you'd think.
That's it
Truly, that's the bulk of markdown. You now know enough to write anything on most of the internet – and to start building things. If you're joining a team that works this way, carry on with the onboarding path 🚀
