What Is Markdown? A Beginner's Guide

Markdown is a way to format text by typing a few extra characters. Write **Friday**, for example, and a Markdown preview shows Friday in bold. Put # before a line, and that line becomes a heading.

You may have seen a file called README.md in a software project. The .md ending means it is a Markdown file. You can open it in a text editor, read it, and change it without needing special document software. An editor with Markdown preview can also show the formatted version.

The easiest way to understand it is to write a short note.

One note, two views

Suppose you are taking notes during a meeting. You could type this:

# Website meeting

The new homepage goes live on **Friday**.

## Before launch

- Check the contact form
- Fix the broken footer link
- Ask Maya to review the copy

In a Markdown preview, “Website meeting” appears as the main heading. “Before launch” becomes a smaller section heading, the hyphens become bullets, and “Friday” appears in bold. The # and ** markers are no longer shown.

Both views come from the same text. Change Friday to Monday in the source, and the preview changes too. You do not have to select the word and press a formatting button each time.

Markdown does not specify a font or a heading color here. Your editor or website supplies those styles, so the note might look slightly different in another app while keeping the same headings and list.

The syntax you will use most

Common Markdown syntax covers text formatting, headings, lists, quotes, links, images, and code. Start with these inline forms; the examples below cover formatting whole blocks of text. The middle column shows exactly what to type.

Inline code is handy when the exact characters matter: a filename such as notes.md, a command, or a setting someone needs to find.

Strikethrough is supported by GitHub Flavored Markdown (GFM), which this site's preview uses, but it is not part of basic Markdown.

Headings and paragraphs

Use # for the document title, ## for a section, and ### for a subsection. Leave a space after the hash marks:

# Trip to Kyoto

## Saturday

### Morning

Visit the market before lunch.

Take the train to the museum afterward.

Here, “Morning” belongs inside “Saturday.” The blank line between the last two sentences makes them separate paragraphs. Pressing Enter only once may leave both lines in the same paragraph when rendered; use a blank line when you mean to start a new one.

Headings go from # through ######, giving you six levels. Choose the level that fits the document hierarchy rather than the size you want the text to be.

For a line break inside the same paragraph, end a line with two spaces before pressing Enter. CommonMark-compatible editors also accept a backslash at the end of the line, which is easier to see in an example:

12 Market Street\
Kyoto, Japan

Bullets and numbered steps

Use hyphens for items, as in the meeting note. Use numbers when the order matters:

1. Open the document.
2. Correct the date.
3. Save a copy.

Indent a list beneath an item to make a nested list. This example uses four spaces before each subitem:

- Prepare the document
    - Check the title
    - Add the missing images
- Share it with the team

Task lists

In apps that support GFM task lists, use - [ ] for an unfinished task and - [x] for a completed one:

- [x] Draft the meeting notes
- [ ] Check the dates
- [ ] Send the final copy

The preview shows checked and unchecked boxes. Whether you can click a box to update the source depends on the app.

Blockquotes

Put > before a line to quote someone or set off a passage:

> Please review the draft before Friday.
>
> Focus on the dates and names.

The > on the otherwise empty line keeps both paragraphs inside the same quote. You can use >> for a quote nested inside another quote.

Horizontal rules

Three hyphens on their own line create a thematic break, usually displayed as a horizontal line. Leave blank lines around them:

End of the meeting notes.

---

Next meeting: Monday.

The blank line before --- matters: directly beneath text, hyphens can instead turn that text into a heading.

Code blocks

To show several lines of code, put three backticks on a line before and after them. A language name after the opening backticks lets compatible apps highlight the code:

```javascript
const greeting = "Hello";
console.log(greeting);
```

The preview displays the two JavaScript lines together in a code block. It does not run them.

Showing punctuation literally

Use a backslash before a formatting character when you want readers to see the character itself:

\*This text keeps its asterisks.\*

\# This is not a heading.

The preview shows the asterisks and hash mark without treating them as formatting. For an entire piece of syntax, inline code or a fenced code block is usually easier to read.

Links and images: where does the address go?

A link puts the clickable words in square brackets and the address in parentheses:

Read the [conversion tutorial](/blog/convert-document-screenshot-to-markdown).

That becomes: Read the conversion tutorial.

An image uses almost the same syntax, with an exclamation mark at the start:

![Handwritten meeting notes](/blog/images/meeting-notes.jpg)

This example tells the app to load meeting-notes.jpg from an images folder beside the Markdown file. The words in brackets describe the image for readers who cannot see it.

The picture is a separate file. If you send someone only notes.md, they will not receive that picture with it. Keep the image folder with the document, or use an image URL the reader can access.

Tables need support from your app

For a small comparison, you can write a table like this:

| Task | Owner |
| --- | --- |
| Check contact form | Maya |
| Review homepage | Sam |

On this site, it renders as:

The pipes separate columns, and the row of hyphens separates the headings from the data. You do not need to pad every cell to the same width.

Add colons to the separator row to request column alignment: :--- for left, :---: for center, and ---: for right. For example:

| Item | Status | Quantity |
| :--- | :---: | ---: |
| Notebooks | Ready | 12 |
| Pens | Ordered | 30 |

To put a literal pipe inside a table cell, escape it as \| so it does not start another column.

Tables are an extension to basic Markdown, so some apps will show the pipe characters instead of a formatted table. Equations and diagrams also need specific support. If you are moving a document between apps, preview those parts in the destination before sharing it.

When would you use Markdown instead of Word?

For meeting notes, study notes, or a project's setup instructions, Markdown gives you a small file that is easy to edit. You can add a section or rearrange a list without adjusting page layout.

For a printed letter with a logo at an exact position, or a report with carefully placed page breaks, Word is usually a better fit. Basic Markdown has no syntax for “put this image exactly two centimeters from the right edge.”

Websites often turn Markdown into HTML. For example, **Friday** can become <strong>Friday</strong>. Markdown saves you from typing those HTML tags while writing ordinary paragraphs and notes.

What if your text is in a screenshot?

Imagine the meeting note above arrives as a screenshot. You can read “Before launch” and the three tasks, but you cannot edit a task directly in the picture.

Image to Markdown uploads the image for server-side recognition and returns Markdown you can edit and preview. A successful conversion could recover ## Before launch and the three bullet points. You would then check the wording against the screenshot, especially names and dates.

Some details need manual work. If the screenshot contains a link labeled “Project plan,” the image usually does not reveal its destination URL. You will need to find that address and add it yourself. The original font and background color also are not part of the recovered Markdown syntax.

The document screenshot tutorial walks through the conversion steps. To try writing Markdown first, copy the meeting note into notes.md, open a Markdown preview, and add a fourth task. You already have the syntax you need: a hyphen, a space, and the task.