Markdown Guide for Beginners: Learn Markdown from Scratch

Markdown is a lightweight markup language that lets you format text using plain text syntax. Created by John Gruber in 2004, Markdown was designed to be as readable as possible in its raw form while still being convertible to structurally rich HTML. Today, Markdown is used everywhere — from GitHub READMEs and documentation to blog posts, notes, and chat messages. This guide will teach you everything you need to start writing in Markdown today.

Want to see your Markdown rendered? Try our free Markdown Preview tool, or convert Markdown to clean HTML with our Markdown to HTML Converter.

What is Markdown?

Markdown is a way to style text on the web. You control the display of the document by formatting words as bold or italic, adding images, creating lists, and more. The key idea is that Markdown-formatted text should be publishable as-is, as plain text, without looking like it's been marked up with tags or formatting instructions.

Unlike HTML, which uses angle brackets and verbose tags, Markdown uses simple punctuation characters that you likely already use in everyday writing. A hash symbol creates a heading. Asterisks create emphasis. Square brackets and parentheses create links. The result is a writing experience that feels natural and efficient.

Headings

Headings are created using hash symbols (#). The number of hashes determines the heading level:

# Heading 1 (largest)
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6 (smallest)

Most documents use Heading 1 for the title and Heading 2 and 3 for sections and subsections. Avoid skipping levels — going from H1 directly to H3 can confuse both readers and screen readers.

Alternatively, you can use underlines for H1 and H2:

Heading 1
=========

Heading 2
---------

Text Formatting

Style	Markdown Syntax	Result
Bold	`bold text` or `__bold text__`	bold text
Italic	`italic text` or `_italic text_`	italic text
Bold + Italic	`*bold and italic*`	*bold and italic*
Strikethrough	`~~strikethrough~~`	~~strikethrough~~
Inline Code	`code`	`code`

Paragraphs and Line Breaks

Create paragraphs by leaving a blank line between blocks of text. Markdown treats consecutive lines of text as a single paragraph — it won't create line breaks where you press Enter.

To create a line break within a paragraph (a soft return), end the line with two or more spaces, then press Enter:

This is the first line.  
This is the second line (with a line break above it).

For a hard line break that creates a new paragraph, leave a blank line between the text blocks.

Lists

Unordered Lists

Use dashes, asterisks, or plus signs followed by a space:

- First item
- Second item
  - Nested item (indent with 2 or 4 spaces)
  - Another nested item
- Third item

You can mix the symbols — Markdown renders them all as bullet points. Consistency is recommended for readability in the source.

Ordered Lists

Use numbers followed by periods:

1. First step
2. Second step
3. Third step

Markdown automatically handles the numbering, so you can use the same number for all items if you want to reorder them later without renumbering:

1. First step
1. Second step
1. Third step
   1. Sub-step (also auto-numbered)

Task Lists

Many Markdown renderers support task lists (GitHub Flavored Markdown):

- [x] Completed task
- [ ] Incomplete task
- [ ] Another incomplete task

Links

Inline Links

[link text](https://example.com)

Links with Titles

[link text](https://example.com "Hover title")

Reference Links

[link text][reference]

[reference]: https://example.com "Optional title"

Reference links keep your paragraphs clean by moving URLs to a separate section, making the source text more readable.

Auto-Links

Most Markdown renderers automatically convert plain URLs into clickable links when you wrap them in angle brackets:

<https://example.com>

Images

Image syntax is similar to links, with an exclamation mark prefix:

![Alt text](image-url.png)

![Alt text](image-url.png "Optional title")

The alt text is important for accessibility and displays when the image fails to load. Keep it descriptive but concise.

Blockquotes

Prefix lines with > to create blockquotes:

> This is a blockquote.
> It can span multiple lines.
>
> > And can be nested with additional > symbols.

Blockquotes can contain other Markdown elements — headings, lists, code blocks, and even other blockquotes.

Code Blocks

For inline code, wrap text in single backticks: `code here`.

For code blocks, wrap the code in triple backticks. Add the language name after the opening backticks for syntax highlighting:

```javascript
function greet(name) {
    return `Hello, ${name}!`;
}
console.log(greet('World'));
```

Common language identifiers include javascript, python, html, css, bash, json, sql, and java. The highlighting depends on the renderer — GitHub supports hundreds of languages.

Indented Code Blocks

Alternatively, indent code by 4 spaces or one tab:

    def hello():
        print("Hello, World!")

This approach is less common now that fenced code blocks with triple backticks are widely supported, but it's part of the original Markdown specification.

Tables

Tables use pipes and hyphens to define columns and rows:

| Header 1 | Header 2 | Header 3 |
| -------- | -------- | -------- |
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

You can align columns by adding colons:

| Left | Center | Right |
| :--- | :----: | ----: |
| Left | Center | Right |

Leading and trailing pipes are optional. The minimum requirement is the header row, a separator row with at least three hyphens per column, and data rows.

Horizontal Rules

Create horizontal rules with three or more hyphens, asterisks, or underscores:

---

***

___

Escape Characters

When you need to display a Markdown special character literally, prefix it with a backslash:

\* This is not italic
\# This is not a heading
\[This is not a link\]

The escapable characters are: \ ` * _ { } [ ] ( ) # + - . ! |

HTML in Markdown

You can use raw HTML within Markdown documents. This is useful for features not supported by standard Markdown, like colored text, embedded videos, or complex layouts:

<details>
<summary>Click to expand</summary>

Hidden content here.

</details>

<kbd>Ctrl</kbd> + <kbd>C</kbd> to copy

Note that not all Markdown renderers process embedded HTML the same way. Test your target platform before relying on HTML elements.

Where Markdown is Used

GitHub: README files, issues, pull requests, discussions, and wikis all use Markdown. GitHub Flavored Markdown (GFM) adds tables, task lists, strikethrough, and more.
Documentation: Platforms like Notion, Confluence, ReadTheDocs, and Docusaurus use Markdown as their primary content format.
Blogging: Static site generators (Hugo, Jekyll, Eleventy, Gatsby) use Markdown for blog posts. CMS platforms like WordPress and Ghost support Markdown editing.
Communication: Slack, Discord, Microsoft Teams, and WhatsApp support Markdown formatting in messages.
Note-Taking: Obsidian, Notion, Bear, Typora, and Apple Notes all support Markdown or use it as their native format.
Technical Writing: API documentation, README files, CHANGELOG files, and technical specifications are commonly written in Markdown.

Markdown Flavors

While the original Markdown specification is quite simple, several "flavors" have emerged that add extra features:

CommonMark: A standardized, unambiguous specification that resolves ambiguities in the original Markdown. The reference implementation is widely used.
GitHub Flavored Markdown (GFM): Extends CommonMark with tables, task lists, strikethrough, auto-links, and emoji shortcodes. Used across all GitHub interfaces.
MultiMarkdown: Adds footnotes, metadata, cross-references, math notation, and more. Popular in academic and long-form writing.
Markdown Extra: Adds tables, fenced code blocks, footnotes, and definition lists. Used in PHP Markdown Extra.

Tips for Writing Better Markdown

Be consistent: Pick a style (two-space indent for nested lists, specific bullet character) and stick with it throughout your document.
Keep lines under 80 characters: Long lines are hard to read in text editors and create messy diffs in version control.
Use blank lines generously: Blank lines separate block elements and make the source text more readable.
Don't over-nest: Deeply nested lists and blockquotes become hard to follow. If you're going beyond 3 levels, consider restructuring.
Write meaningful alt text: For images, always include descriptive alt text — it's essential for screen reader users and appears when images fail to load.

FAQ

Is Markdown a programming language?

No, Markdown is a markup language, not a programming language. It doesn't have variables, logic, loops, or computation. It's a way to add formatting structure to plain text. If you need dynamic content, consider template engines that process Markdown (like Jinja2 or Liquid) or static site generators.

Can I use Markdown in Microsoft Word or Google Docs?

Google Docs doesn't natively support Markdown input, though browser extensions can add this functionality. Microsoft Word also lacks native Markdown support. For a Markdown-friendly writing experience, use dedicated editors like Typora, Obsidian, VS Code, or Mark Text instead.

What's the difference between Markdown and HTML?

Markdown is designed to be a simpler, more readable alternative to HTML for writing content. Markdown converts to HTML — every Markdown document is ultimately rendered as HTML in the browser. Think of Markdown as a shorthand for common HTML elements. For anything beyond basic formatting (complex layouts, forms, scripts), you'd still need HTML.

How do I add math equations in Markdown?

Standard Markdown doesn't support math, but many renderers do through extensions. LaTeX math notation using dollar signs is the most common approach: $E = mc^2$ for inline math and $$E = mc^2$$ for display math. GitHub, Notion, and most documentation platforms support this through MathJax or KaTeX rendering.

Can Markdown handle images and file attachments?

Markdown can reference images via URL or relative file path, but it doesn't embed binary data. For local images, you reference them by path: ![](./images/photo.png). For file attachments, you'd typically link to them: [Download PDF](./files/document.pdf). The actual files need to be hosted or stored separately.

Is there a spell checker for Markdown?

Yes. Most code editors (VS Code, Sublime Text, Atom) have spell-checking extensions that work with Markdown files. Dedicated tools like vale, markdownlint, and write-good can also check grammar, style, and common writing mistakes in Markdown documents. VS Code's Code Spell Checker extension is particularly popular and works well out of the box.

How do I convert Markdown to PDF?

Several options exist: Pandoc (command-line tool that converts between many formats), browser print (render the Markdown as HTML, then print to PDF), or dedicated tools like md-to-pdf, grip, or Markdown PDF. For professional-quality output with custom styling, Pandoc combined with LaTeX or CSS gives you the most control over the final appearance.

What's the best Markdown editor for beginners?

For beginners, we recommend Typora (wysiwyg, no split-screen confusion), Obsidian (free, with preview and lots of plugins), or Dillinger (web-based, no installation needed). VS Code with the Markdown All in One extension is great if you already use it for coding. The key is picking an editor with live preview so you can see the rendered output as you type.