Markdown is a lightweight markup language that lets you write formatted text using plain text syntax. Created by John Gruber in 2004, it has become the standard for writing documentation, README files, blog posts, notes, and even books. If you have ever written a GitHub README or a Stack Overflow answer, you have used Markdown.
Why Markdown?
Markdown solves a simple problem: how do you write formatted text that is readable as plain text but renders beautifully as HTML? Unlike Word documents or Google Docs, Markdown files are plain text — they work in any text editor, version control systems (like Git), and every operating system. They are also future-proof: a Markdown file written in 2004 is still perfectly readable today.
Essential Markdown Syntax
Headings
Use # symbols for headings. One # is a top-level heading, two is a subheading, and so on up to six levels:
# Heading 1
## Heading 2
### Heading 3
#### Heading 4Text Formatting
Wrap text in special characters to format it:
**bold text** renders as bold text
*italic text* renders as italic text
~~strikethrough~~ renders as strikethrough
`inline code` renders as inline code
Lists
Unordered lists use - or * or +. Ordered lists use numbers:
- Item one
- Item two
- Nested item
1. First
2. Second
3. ThirdLinks and Images
[link text](https://example.com) creates a link.
 embeds an image.
Reference-style links store the URL separately: [link text][ref] with [ref]: https://example.com at the bottom.
Tables
| Name | Price | Stock |
|---------|-------|-------|
| Widget | $9.99 | 50 |
| Gadget | $24.99| 12 |Blockquotes and Code Blocks
Blockquotes use >:
> This is a blockquote
Fenced code blocks use triple backticks with an optional language identifier:
```javascript
const x = 42;
console.log(x);
```Common Markdown Pitfalls
- Missing blank lines. Many Markdown parsers require a blank line before headings, lists, and blockquotes. Without them, the formatting may not render.
- Inconsistent list markers. Mixing
-,*, and+in the same list can cause issues in strict parsers. - Special characters in text. Characters like
*,_,[, and#have special meaning. Escape them with a backslash:\*. - Line breaks. In most Markdown flavors, a single newline does not create a line break in the rendered output. You need either two spaces at the end of the line or a blank line between paragraphs.
Where Markdown Is Used
Markdown has become ubiquitous across the software industry:
- GitHub: README files, issue templates, pull request descriptions, wiki pages
- Documentation: Docs-as-code tools like Docusaurus, MkDocs, and GitBook all use Markdown
- Note-taking: Obsidian, Notion, Bear, and Typora all support Markdown
- Static site generators: Hugo, Jekyll, and Eleventy convert Markdown into HTML pages
- Chat platforms: Discord, Slack, and Telegram support Markdown formatting
Try It Yourself
The best way to learn Markdown is to write it. Open the ToolShack Markdown Editor and start typing. Type some headings, bold text, a list, and a code block. See the live preview update in real time. Within 15 minutes, you will have the core syntax memorized.
Conclusion
Markdown is one of those rare skills that takes 10 minutes to learn and pays off for a lifetime. Whether you are writing a README, drafting documentation, or taking notes, Markdown gives you clean, portable, future-proof formatted text. Master the basics — headings, lists, links, code blocks, and tables — and you will be more productive in every text-based workflow you encounter.