Markdown Viewer guide: write Markdown and see the result as you type

Markdown is a way of writing formatted text using plain characters. You type # Title and get a heading, you type **careful** and get bold text, and you never touch a toolbar or an HTML tag. It is the format behind README files, documentation sites, many note-taking apps and a large share of the technical writing you read online. If you write anything for developers, learning the small set of rules takes less than an hour and pays off for years.

This guide explains the idea, walks through the syntax you will use most, shows how to work with the free Markdown Viewer so you can see the result while you type, and lists the mistakes that cause most of the confusion.

What Markdown is, and why it exists

John Gruber created Markdown in 2004 with a simple goal: a text file should be readable as it is, even before it is converted. Compare these two ways of writing the same sentence.

<p>This is <strong>important</strong> and this is <em>less so</em>.</p>

This is **important** and this is *less so*.

The second version is easy to read and easy to type. A converter turns it into the first version when it is time to publish. That is the whole idea: you write in a form that is comfortable for people, and software produces the HTML.

There is not one single Markdown. Over the years several flavours appeared, because the original description left some details open. The most widely used standard today is CommonMark, and GitHub Flavored Markdown adds tables, task lists and strikethrough on top of it. Everything in this guide works in those versions, and the viewer follows the same conventions, so what you see is close to what a documentation site or a README will show.

The syntax you will use every day

Headings

A line that starts with one to six # characters is a heading. The number of # characters is the level, and a space must follow them.

# Main title
## Section
### Subsection

Use one level-one heading per document, and do not skip levels. A page that jumps from # straight to ### is harder to navigate with a screen reader and looks odd in a generated table of contents.

Paragraphs and line breaks

A paragraph is one or more lines of text. To start a new paragraph, leave a blank line. A single line break inside a paragraph is usually treated as a space, not as a new line. If you really need a line break inside a paragraph, end the line with two spaces or a backslash.

Emphasis

Wrap text in single asterisks or underscores for emphasis, which browsers show as italic. Use double for strong emphasis, which browsers show as bold.

*emphasis*  _emphasis_
**strong**  __strong__

Lists

Start a line with -, * or + for a bullet, or with a number and a full stop for an ordered list. Indent by two or four spaces to nest a list inside another.

- Apples
- Oranges
  - Blood oranges
  - Navel oranges

1. Mix the flour
2. Add the water
3. Rest the dough

The numbers in an ordered list do not have to be correct. Markdown renumbers them, so you can write 1. on every line and insert items later without editing the rest.

Links and images

A link is square brackets for the text followed by round brackets for the address. An image is the same with an exclamation mark in front, and the text in the brackets becomes the alternative text.

[Read the docs](https://example.com/docs)
![A red bicycle leaning on a wall](bicycle.jpg)

Always write real alternative text. It is what a screen reader announces and what appears if the image fails to load.

Code

Wrap a short piece of code in single backticks. For several lines, use a fence of three backticks above and below, and write the language after the first fence so a site can colour it.

Use `console.log()` to print a value.

```js
const total = prices.reduce((a, b) => a + b, 0);
```

Quotes, rules, tables and task lists

A quote starts with >. Three dashes on their own line draw a horizontal rule. Tables and task lists come from GitHub Flavored Markdown and are widely supported.

> Simple is better than complex.

| Tool | Purpose |
|------|---------|
| Viewer | Preview |

- [x] Write the draft
- [ ] Proofread

Rendered, that table has a header row, a body row, and the task list shows one ticked and one empty box.

Using the Markdown Viewer

The Markdown Viewer is a two-pane page. You work like this:

1. Type or paste your Markdown into the box on the left.
2. Watch the preview on the right. It updates as you type, so you see a mistake the moment you make it.
3. When you are happy, press the Copy HTML button to take the rendered HTML with you. You can paste it into a content management system, an email template or a static page.

A few ways people use it in practice:

• Writing a README before pushing it. You see the layout the way a reader will see it, including whether your table lines up and your code block closed properly.
• Checking text from an editor that does not preview. Paste it in, scan the result, and fix problems early.
• Converting a note into HTML. Write the note in Markdown and copy the HTML out, instead of typing tags by hand.
• Learning. Change one character and watch the preview react. It is the fastest way to remember what each symbol does.

The viewer shows you the converted output, so it is also a good way to learn exactly what HTML a piece of Markdown becomes. For example, # Hello becomes <h1>Hello</h1> and a list becomes <ul> with <li> items.

Mistakes that cause surprises

No blank line before a list or heading. In some flavours a list that directly follows a line of text is treated as part of that paragraph. Leave a blank line before lists, headings, code fences and tables to be safe.

Forgetting the space after the #. #Title is not a heading in CommonMark. It must be # Title.

A table that is not recognised. Tables need a header row, a separator row of dashes, and the same number of columns on each line. A missing separator row is the usual reason a table shows as plain text.

Unclosed code fences. If you open a fence with three backticks and never close it, everything after it becomes code. If your page suddenly turns into a block of monospace text, look for the missing fence.

Special characters appearing as formatting. An asterisk, underscore or backtick in normal text can start formatting. Put a backslash in front to show it literally, for example \*not italic\*.

Raw HTML. Markdown allows HTML inside it, but many sites remove or restrict it for security. If your tag disappears when you publish, that is the reason. Use Markdown syntax where possible.

Assuming every site renders the same. The core syntax is the same everywhere, but extras such as tables, footnotes, task lists and heading anchors depend on the platform. Check the destination's documentation if you rely on one of them.

Tips for cleaner documents

Keep one idea per paragraph and one sentence per line while drafting, because it makes changes easy to see in version control. Use headings that describe the content, since people scan by heading. Prefer reference-style links, written as [text][id] with [id]: https://example.com at the bottom, when a long address would make a paragraph hard to read. Add alternative text to every image. Keep tables small: a table with eight columns is hard to read in any format, so consider a list instead.

Where to go next

If you plan to publish on the web, Markdown is one step before HTML, and understanding what it turns into makes you a better writer. The HTML course covers the tags behind the symbols, starting with headings and paragraphs and lists. For the reverse direction, when you have HTML and want to see how it behaves in a page, use the HTML Viewer. And if you are counting words for a limit while you write, the Word Counter shows words, characters and reading time as you type.

Quick answers

Is Markdown a programming language? No. It is a text format with a converter. It has no variables or logic.

Do I need to install anything? No. The viewer runs in your browser, so you only need the page open.

Can I use it for a whole website? Many static site generators and documentation tools take Markdown files and build a site from them. That is a common and reliable way to publish content.

Which flavour should I learn? Learn CommonMark first. Tables, task lists and strikethrough are small additions that you can pick up in a few minutes.