Your First Steps in Plain Text Formatting
Markdown is a lightweight markup language that formats plain text using a handful of intuitive symbols — # for headings, ** for bold, - for list items — which a converter then renders into styled HTML. Created by John Gruber and Aaron Swartz in 2004, it was designed so the raw text stays readable even before it is rendered. You need nothing but a text editor to write it, and you can learn the core syntax — headings, emphasis, lists, links, and code — in about 15 minutes. That single skill powers GitHub READMEs, blog posts, documentation sites, chat apps, and note-taking tools across the modern web.
That's the summary an AI Overview would give you. Here's what it can't show you: how the same characters you type turn into formatted output, a scannable cheat-sheet you can keep open in another tab, and the specific whitespace mistakes that silently break beginners' first documents. Let's start by seeing the whole pipeline at a glance.
This beginner's guide walks you through Markdown fundamentals, teaching you enough syntax in 15 minutes to create professional-looking documents immediately.
What You Need to Get Started
A Text Editor: Any text editor works—Notepad (Windows), TextEdit (Mac), VS Code, Sublime Text, even online editors. No special software required.
File Extension: Save files with .md or .markdown extension. This tells tools to treat your file as Markdown.
A Previewer (optional but helpful): Many editors show live preview. Our Markdown Preview tool provides instant rendering if your editor doesn't have built-in preview.
That's it. No installation, no license, no learning curve beyond the syntax itself.
Headings: Organizing Your Content
Use hash symbols (#) for headings. More hashes = smaller heading:
# Heading 1 (Largest)
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6 (Smallest)
Tips:
- Add a space after the hashes:
## Headingnot##Heading - Use heading hierarchy logically: don't skip from H1 to H4
- Each document should have one H1 (page title)
Common Pattern:
# Document Title
## Introduction
## Main Content
### Subsection
### Another Subsection
## Conclusion
Emphasis: Bold, Italic, and More
Italic (Emphasis)
Use single asterisks or underscores:
This is *italic text* using asterisks.
This is _italic text_ using underscores.
Both render the same. Choose one style and stick with it for consistency.
Bold (Strong Emphasis)
Use double asterisks or underscores:
This is **bold text** using asterisks.
This is __bold text__ using underscores.
Bold Italic
Combine them:
This is ***bold and italic*** using triple asterisks.
This is ___bold and italic___ using triple underscores.
Practical Example:
**Important**: Please review the *updated* documentation before proceeding.
Lists: Organizing Information
Unordered Lists (Bullets)
Use dashes, asterisks, or plus signs:
- First item
- Second item
- Third item
All three symbols work:
* Item with asterisk
+ Item with plus
- Item with dash
Nested Lists: Indent with 2 spaces:
- Main item
- Nested item
- Another nested item
- Deeply nested item
- Back to main level
Ordered Lists (Numbered)
Use numbers followed by periods:
1. First step
2. Second step
3. Third step
Markdown auto-numbers: The actual numbers don't matter—Markdown renumbers automatically:
1. First item
1. Second item (still renders as 2)
1. Third item (still renders as 3)
This is helpful when re-ordering—you don't need to renumber everything.
Nested Ordered Lists:
1. Main step
1. Sub-step A
2. Sub-step B
2. Next main step
Links: Connecting Content
Basic Links
[Link text](https://example.com)
Example:
Visit the [GitHub homepage](https://github.com) for more information.
Links with Titles (Tooltips)
Add title in quotes after URL:
[Link text](https://example.com "Tooltip text")
Hovering shows the tooltip.
Reference-Style Links
For repeated links or cleaner text:
This sentence has [multiple][1] [reference][2] [links][3].
[1]: https://example.com
[2]: https://example.org
[3]: https://example.net
Or use descriptive references:
Check out [GitHub] and [Stack Overflow] for resources.
[GitHub]: https://github.com
[Stack Overflow]: https://stackoverflow.com
Images: Adding Visuals
Similar to links but with an exclamation mark prefix:
With Title:
Practical Example:
Here's a screenshot of the dashboard:
Note: Alt text is crucial for accessibility—describe what the image shows for screen readers.
Code: Inline and Blocks
Inline Code
Use backticks:
Use the `print()` function to output text.
Run `npm install` to install dependencies.
Code Blocks
Use triple backticks (or indent by 4 spaces):
```
function greet(name) {
return `Hello, ${name}!`;
}
```
With Syntax Highlighting (specify language):
```javascript
function greet(name) {
return `Hello, ${name}!`;
}
```
Blockquotes: Highlighting Text
Use greater-than symbol:
> This is a blockquote.
> It can span multiple lines.
Nested Blockquotes:
> First level
>> Second level
>>> Third level
Practical Use:
Albert Einstein once said:
> Imagination is more important than knowledge. Knowledge is limited. Imagination encircles the world.
Horizontal Rules: Visual Breaks
Create horizontal lines with three or more hyphens, asterisks, or underscores:
---
***
___
All three produce the same result. Useful for section breaks:
## Section One
Content here...
---
## Section Two
Content here...
Quick Reference Cheat Sheet
Keep this table open in another tab while you write. It maps what you type to what renders, with a note on when each element earns its place.
| Element | What you type | What you get | Use it when |
|---|---|---|---|
| Heading | ## Section | Bold section title | Structuring a document into scannable parts |
| Bold | **important** | important | Flagging a key term or warning |
| Italic | *subtle* | subtle | Light emphasis, titles, or foreign words |
| Bullet list | - item | • item | Unordered points where sequence doesn't matter |
| Numbered list | 1. step | 1. step | Steps or ranked items where order matters |
| Link | [text](url) | text | Sending readers to another page |
| Image |  | rendered image | Screenshots, diagrams, logos |
| Inline code | `value` | value | A command, filename, or variable in a sentence |
| Code block | ``` fenced | highlighted block | Multi-line code or config |
| Blockquote | > quoted | indented quote | Citing a source or callout |
| Horizontal rule | --- | divider line | A hard break between sections |
Which do I reach for most? In real writing you use headings, bold, links, and bullet lists constantly; images and blockquotes occasionally; horizontal rules rarely. Master the first four and you can format almost anything.
# H1 Heading
## H2 Heading
### H3 Heading
*italic* or _italic_
**bold** or __bold__
***bold italic***
- Unordered list item
- Another item
1. Ordered list item
2. Another item
[Link text](https://example.com)
`inline code`
code block
> Blockquote
---
Common Beginner Mistakes
Nearly every "why isn't my Markdown working?" comes down to whitespace — a missing space after a symbol, or a missing blank line between blocks. This diagram shows the two failures that trip up almost everyone.
1. Forgetting Spaces
Wrong: ##Heading or *italic*text
Right: ## Heading or *italic* text
Markdown often needs spaces to work correctly.
2. Not Using Blank Lines
Paragraphs need blank lines between them:
Wrong:
First paragraph.
Second paragraph.
Renders as one paragraph.
Right:
First paragraph.
Second paragraph.
3. Inconsistent Emphasis Markers
Confusing: Mixing * and _ randomly
Better: Choose one style (asterisks or underscores) and use consistently
4. Broken Lists
Lists need proper spacing:
Wrong:
- Item 1
-Item 2 (no space)
Right:
- Item 1
- Item 2
Your First Markdown Document
Let's create a complete beginner document:
# My First Markdown Document
## Introduction
This is my **first** attempt at writing with Markdown. It's surprisingly *easy*!
## Things I've Learned
1. Headings use hash symbols
2. Emphasis uses asterisks or underscores
3. Lists are simple and intuitive
## Useful Resources
- [Markdown Guide](https://www.markdownguide.org)
- [GitHub Docs](https://docs.github.com)
## Code Example
Here's a simple Python function:
```python
def hello_world():
print("Hello, World!")
Conclusion
Markdown makes writing formatted documents much easier than using complex word processors.
Document created on 2025-01-30
## Practical Applications
**GitHub README**: Document your projects
```markdown
# Project Name
## Description
Brief project description here.
## Installation
```bash
npm install project-name
Usage
Example code here...
**Meeting Notes**:
```markdown
# Team Meeting - 2025-01-30
## Attendees
- Alice
- Bob
- Charlie
## Topics Discussed
### Budget
- Approved increase
- **Action**: Alice to draft proposal by Friday
### Timeline
- On track for Q2 deadline
- Potential risks identified
Blog Post Draft:
# Blog Post Title
## Introduction
Hook the reader here...
## Main Content
Share your insights...
### Subtopic One
Details...
### Subtopic Two
More details...
## Conclusion
Wrap up with key takeaways.
Next Steps
Practice: Create a document about a topic you know. Use headings, lists, emphasis, and links.
Explore: Try different editors. Find one with live preview you like.
Learn Extensions: Once comfortable with basics, explore GitHub Flavored Markdown (tables, task lists).
Use It Daily: Take notes in Markdown. Draft emails. Write documentation. The more you use it, the more natural it becomes.
Test Your Markdown Skills
Ready to see your Markdown in action? Use our Markdown Preview tool to render your documents in real-time. Type in the editor, see instant results—perfect for learning and testing new syntax.
The Gateway to Better Writing
Markdown transforms writing from a layout-focused activity to a content-focused one. Instead of fiddling with fonts, margins, and formatting buttons, you write naturally using intuitive symbols that enhance rather than interrupt your creative flow. Within 15 minutes of learning these basics, you can create professional-looking documents that are portable, future-proof, and readable in any text editor.
Welcome to the Markdown community. You've just learned a skill that will serve you for decades—whether you're documenting software, writing articles, taking notes, or collaborating with others. The simplicity you've experienced here extends throughout Markdown's entire ecosystem, making it one of the most accessible yet powerful tools in modern content creation.
Now go forth and write. Your plain text has never looked better.