How to Write in Markdown: A Complete Guide to the Syntax

Learning how to write in markdown is one of the most practical skills you can pick up as a writer, developer, or knowledge worker. Markdown is a lightweight markup language that lets you add formatting to plain text using simple punctuation characters. Within minutes of learning the basics, you can produce clean, well-structured documents that render beautifully in any markdown-compatible tool.

Quick Answer: To write in markdown, use # for headings, **text** for bold, *text* for italic, - for bullet lists, and [text](url) for links. Markdown was created in 2004 and is now the default format for over 200 million GitHub repositories, technical documentation, and static site generators worldwide.

This guide walks through every core element of markdown syntax with working examples you can copy and try immediately.

What Is Markdown and Why Does It Matter?

Markdown was created by John Gruber in 2004 with a simple philosophy: formatting should be readable even in plain text form. A bold word wrapped in asterisks is still readable as plain text. A heading preceded by a hash symbol still makes visual sense before it is rendered.

This philosophy makes markdown documents:

• Portable - plain text files open everywhere, on any device, forever
• Version-control friendly - diffs are human-readable because the source is plain text
• Fast to write - no reaching for the mouse to click formatting buttons
• Consistent - the same input always produces the same output

Markdown is now the default writing format for GitHub READMEs, technical documentation, static site generators, note-taking apps, and a wide range of online publishing platforms. GitHub alone hosts over 200 million public repositories, virtually all using markdown for documentation.

How Do You Create Headings in Markdown?

Headings are created with the hash character (#). The number of hashes determines the heading level, from H1 through H6.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Best practice: use only one H1 per document (typically the document title), then H2 for main sections, H3 for subsections, and so on. Skipping heading levels (going from H2 directly to H4) is considered poor practice for accessibility and document structure.

How Do You Make Text Bold and Italic in Markdown?

Emphasis is the foundation of readable prose formatting.

Bold text is wrapped in double asterisks or double underscores:

**this is bold**
__this is also bold__

Italic text uses single asterisks or single underscores:

*this is italic*
_this is also italic_

You can combine both to produce bold italic text:

***bold and italic***

As a rule of thumb, prefer asterisks over underscores for emphasis. Underscores can behave unexpectedly inside words with some markdown parsers.

For a deeper look at all the ways to emphasize text in markdown, including strikethrough and highlight syntax, see the guide on bold and italic in markdown.

How Do Paragraphs and Line Breaks Work in Markdown?

A blank line between two blocks of text creates a new paragraph. A single newline within a paragraph does not create a line break in the rendered output.

This is the first paragraph.

This is the second paragraph.

To force a line break within a paragraph without starting a new one, end the line with two or more spaces before pressing Enter. This is called a hard line break.

How Do You Create Unordered Lists in Markdown?

Use a hyphen (-), asterisk (*), or plus sign (+) followed by a space to create a bullet list:

- First item
- Second item
- Third item

Nest items by indenting with two or four spaces:

- Main item
  - Sub-item
  - Another sub-item
- Back to main level

How Do You Create Ordered Lists in Markdown?

Start lines with numbers followed by a period:

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

Interesting quirk: most markdown renderers do not care about the actual numbers you use. The list below renders as 1, 2, 3 regardless:

1. First
1. Second
1. Third

This is useful when you are frequently inserting or reordering items and do not want to renumber the whole list every time.

How Do You Add Links in Markdown?

Links follow the pattern [link text](URL).

[Visit edtr.md](/app)
[Markdown on Wikipedia](https://en.wikipedia.org/wiki/Markdown)

You can add an optional title that appears as a tooltip:

[edtr.md](/app "Free in-browser markdown editor")

For documents with many links, reference-style links keep the prose clean:

Check out [edtr.md][editor] for a fast writing experience.

[editor]: /app "Free in-browser markdown editor"

How Do You Add Images in Markdown?

Image syntax is almost identical to link syntax, with an exclamation mark prepended:

![Alt text describing the image](path/to/image.png)

The alt text inside the square brackets is critical for accessibility and SEO. It describes the image content for screen readers and search engines. Images with meaningful alt text also perform significantly better in Google Image Search.

How Do You Format Code in Markdown?

For inline code, wrap text in single backticks:

Use the `console.log()` function to debug.

For multi-line code blocks, use triple backticks. You can specify a language after the opening backticks to enable syntax highlighting:

```javascript
function greet(name) {
  return `Hello, ${name}`;
}
```

Code blocks are one of markdown’s strongest features, especially for technical writing. They preserve indentation and spacing exactly as written. According to the 2023 Stack Overflow Developer Survey, over 75% of professional developers write documentation in markdown, and fenced code blocks with syntax highlighting are the most-used extended feature. For a full breakdown of every code formatting option, see the markdown code formatting guide.

How Do You Create Blockquotes in Markdown?

Prefix a line with > to create a blockquote:

> The best writing tool is the one you actually use.

Blockquotes can span multiple paragraphs and can be nested:

> First level of quoting.
>
> > Nested blockquote.

How Do You Add Horizontal Rules in Markdown?

Three or more hyphens, asterisks, or underscores on a line by themselves create a horizontal rule:

---

How Do You Create Tables in Markdown?

Tables use pipes (|) and hyphens to define columns and headers:

| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Row 1    | Data     | Data     |
| Row 2    | Data     | Data     |

Colons in the separator row control alignment:

| Left | Center | Right |
|:-----|:------:|------:|
| a    | b      | c     |

For a comprehensive look at markdown table formatting, see the markdown tables guide.

How Do You Escape Special Characters in Markdown?

To display a character that would otherwise be interpreted as markdown formatting, precede it with a backslash:

\*This text is not italic\*

Characters you can escape include: \, `, *, _, {, }, [, ], (, ), #, +, -, ., !

How Do Task Lists Work in Markdown?

Many markdown renderers support task list syntax using [ ] for incomplete tasks and [x] for completed ones:

- [x] Install a markdown editor
- [x] Learn basic syntax
- [ ] Write first document
- [ ] Share with the team

Task lists are excellent for tracking work. For more detail, see the guide on markdown task lists. Task lists are part of GitHub Flavored Markdown, one of the most widely used extended dialects. You can explore the full set of non-standard features in the markdown extended syntax guide.

What Are the Best Practices for Writing in Markdown?

Keep a cheat sheet close. Syntax lookups slow you down when you are learning. Bookmark a reference so you can move fast without breaking concentration.

Write first, format later. Get your thoughts down in plain prose, then go back and apply headings, emphasis, and structure. Trying to format while composing splits your attention.

Use a live preview. Seeing the rendered output alongside your source eliminates guesswork. You immediately catch formatting errors like unclosed asterisks or misaligned table columns.

Be consistent with your conventions. Pick one style for bullet list markers (- vs *) and stick with it across a project. Consistency reduces cognitive load when reading the source.

Lint your markdown. Tools like markdownlint can flag common issues such as inconsistent heading levels, trailing spaces, and bare URLs.

What to Try Next

The fastest way to get comfortable with markdown is to start writing in it today. Open edtr.md in your browser, no download or account required, and start typing. The live preview shows you exactly how your document will look as you build it. Within an hour of practice, the syntax will feel completely natural.

If you want a quick-reference card covering all the syntax from this guide in condensed form, the markdown cheat sheet has everything in one place.

New to markdown entirely? The markdown for beginners guide walks through the same core syntax with a gentler learning curve and a ready-to-use starter template.