How to Write Markdown: A Beginner's Guide

Markdown is a way to format plain text files using simple symbols. You type # for a heading, ** for bold, and - for a bullet point. A renderer turns those symbols into formatted output. This guide walks you through every step, from your first file to publishing a complete document.

Step 1: Create a Markdown File

Open any text editor (VS Code, Sublime Text, Notepad, TextEdit) and create a new file. Save it with a .md extension:

notes.md
meeting-notes.md
README.md

The .md extension tells editors and tools to treat the file as markdown. The content inside is plain text.

Step 2: Write a Heading

Headings use # symbols. One # is the biggest heading, six ###### is the smallest:

# My Document Title

## Introduction

### Background

Always put a space between the # and your text. The heading level creates a hierarchy for your document, like chapters and sections in a book.

For your first document, start with one # for the title and ## for sections. You rarely need more than three levels.

Step 3: Write Paragraphs

Just type normally. Paragraphs are separated by a blank line:

This is the first paragraph. It can be as long as you want.
Lines next to each other get joined into a single paragraph.

This is a new paragraph because there is a blank line above it.

A single line break (Enter once) does not create a new paragraph in most renderers. You need a blank line.

Step 4: Format Text

Bold wraps text in double asterisks. Italic wraps text in single asterisks:

This word is **bold** and this word is *italic*.

You can combine them: ***bold and italic***.

Strikethrough uses double tildes:

This is ~~no longer relevant~~.

A few rules of thumb:

• Use bold for key terms, warnings, and anything that must stand out
• Use italic for first mentions of technical terms, book titles, and light emphasis
• Use strikethrough for corrections or removed content

See the bold and italic guide for edge cases and platform differences.

Step 5: Add Links

Links use [text](url):

[MDtoLink](https://mdtolink.com)
[Getting Started Guide](https://mdtolink.com/docs/getting-started)

The text in square brackets is what readers see. The URL in parentheses is where the link goes. Always include https:// for absolute URLs.

For email links:

<hello@example.com>

See the markdown links guide for reference-style links, anchor links, and more.

Step 6: Add Images

Images are almost identical to links, with an ! prefix:

![A screenshot of the editor](/images/editor.png)

The text in brackets is the alt text (a description for screen readers and fallback display). The URL points to the image file.

See the markdown images guide for sizing, captions, and linked images.

Step 7: Create Lists

Bullet lists use dashes:

- First item
- Second item
- Third item

Numbered lists use numbers:

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

Nested lists use indentation (2 spaces):

- Category
  - Sub-item one
  - Sub-item two
- Another category

Task lists add checkboxes:

- [x] Done
- [ ] Not done yet

See the markdown lists guide for nesting rules and the task lists guide for checklists.

Step 8: Add Code

Inline code uses single backticks:

Run `npm install` to install dependencies.

Code blocks use triple backticks. Add a language name for syntax highlighting:

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

Common language identifiers: javascript, typescript, python, bash, json, html, css.

See the code blocks guide for the full language list and advanced usage.

Step 9: Add Blockquotes

Prefix lines with >:

> This is a blockquote. Use it for quotes,
> notes, or highlighted information.

Blockquotes are useful for callouts and warnings in documentation:

> **Note:** This feature requires a Pro plan.

See the blockquotes guide for nesting and GitHub-style admonitions.

Step 10: Add a Table

Tables use pipes and dashes:

| Name    | Role      | Status |
|---------|-----------|--------|
| Alice   | Developer | Active |
| Bob     | Designer  | Active |

Tables need at least a header row and a separator row (the dashes). The pipes do not need to align visually, but it helps readability.

See the markdown tables guide for alignment and advanced usage.

Step 11: Add a Horizontal Rule

Three dashes create a divider line:

---

Use horizontal rules sparingly to separate distinct sections of a document. Headings are usually a better choice for structure.

Putting It All Together

Here is a complete markdown document using everything above:

# Project Status Update

## Summary

The **v2.0 release** is on track for March 15. All critical features
are complete and in testing.

## Completed

- [x] User authentication
- [x] API rate limiting
- [x] Dashboard redesign

## In Progress

- [ ] Performance testing
- [ ] Documentation updates

## Key Metrics

| Metric | Target | Current |
|--------|--------|---------|
| API latency | < 200ms | 145ms |
| Test coverage | > 80% | 82% |
| Open bugs | 0 critical | 0 critical |

## Next Steps

1. Complete performance testing by March 10
2. Publish release notes
3. Deploy to production

> **Note:** The deployment window is scheduled for 2:00 AM UTC.

For details, see the [release plan](https://example.com/release-plan).

---

*Last updated: March 4, 2026*

Common Beginner Mistakes

Forgetting blank lines. Paragraphs, lists, and code blocks usually need a blank line before them. Without it, some parsers join everything into one block.

Spaces matter. #Heading (no space) is not a heading. - Item needs a space after the dash. [text] (url) (space between brackets and parentheses) breaks the link.

Not closing formatting. An unclosed ** makes everything after it bold. Always close what you open.

Mixing tabs and spaces. Use spaces for indentation. Tabs can cause inconsistent rendering across parsers.

Tools for Writing Markdown

FAQ

How long does it take to learn markdown?

Most people learn the basics (headings, bold, italic, links, lists) in 15-30 minutes. The full syntax, including tables, code blocks, and footnotes, takes a few hours of practice.

Is markdown the same on every platform?

The core syntax is the same everywhere. Extensions like tables, task lists, and strikethrough are part of GitHub Flavored Markdown (GFM), which is supported by most modern tools. Some platforms add their own features on top.

Can I write markdown on my phone?

Yes. Apps like iA Writer, Obsidian Mobile, and 1Writer support markdown on iOS and Android. You can also use any plain text editor since markdown files are just text.

What happens when I make a mistake in markdown?

Nothing breaks. The worst case is that your formatting does not render as expected. The raw symbols show up as literal text, and you can fix them. Markdown is forgiving.

Try It Out

Open the MDtoLink editor and start typing. The preview updates as you write. When your document is ready, publish it to a shareable URL with one click.

For the full syntax reference, see the markdown cheat sheet. To understand the most popular flavor, see What Is GitHub Flavored Markdown?.