Markdown Syntax Guide for Beginners

What Markdown is and why it is useful

Markdown is a lightweight syntax for structuring plain text. A few familiar characters create headings, emphasis, lists, links and code, while the source remains readable even before it is rendered. Markdown files commonly use the .md extension.

It is useful for README files, technical documentation, notes and other writing that benefits from being easy to edit, compare and keep in version control. A renderer converts the syntax into HTML or another format. The original Markdown description left some behavior open, so CommonMark provides a more consistent core specification. GitHub Flavored Markdown (GFM) adds features such as tables, task lists and strikethrough. Because support varies, preview a document in its destination.

The core Markdown syntax

Headings

Start a heading with one to six # characters. More characters indicate a lower-level heading. Add a space after the hashes, use one main heading for the document title, and keep heading levels in order.

# Project notes
## Setup
### Requirements

A consistent hierarchy makes long documents easier to scan and helps assistive technology and search systems interpret the page structure when it is published as HTML.

Paragraphs and line breaks

A blank line separates paragraphs. A single newline inside a paragraph is usually rendered as a space. To force a line break without starting a new paragraph, end the line with two spaces or a backslash:

First line\
Second line

Bold, italic and strikethrough

Use one * or _ for italic text and two for bold. Three markers can combine both styles. Strikethrough with two tildes is a GFM extension.

*italic* and **bold**
***bold and italic***
~~removed text~~

Lists

Use -, * or + for unordered lists. For ordered lists, put a number and period before each item. Indent nested items consistently. GFM also supports task lists:

- Review the draft
- Check the examples
  - Confirm the code block

1. Open the editor
2. Write the content
3. Preview the result

- [x] Write the draft
- [ ] Proofread

Renderers generally count ordered-list items from the first number, so the source numbers do not always need to be sequential.

Links and images

Put link text in square brackets and its destination in parentheses. An image uses the same pattern with an exclamation mark before the brackets:

[Markdown Editor](/tools/markdown-editor)
![A description of the image](images/diagram.png)

Choose link text that explains where the link leads. Give images meaningful alt text so people using screen readers can understand their purpose, and so the description can appear if an image does not load.

Blockquotes and code

Start a quoted line with >. Wrap a short code term in backticks. For longer examples, use three backticks on separate lines; adding a language name can enable syntax highlighting where the renderer supports it.

> Keep examples easy to read.

Run `npm install` to install dependencies.

```json
{"name": "Maya", "active": true}
```

When documenting JSON, check that the example is valid with the JSON Formatter & Validator. To display triple backticks inside another fenced block, use a longer fence around the outer example.

Tables and horizontal rules

Tables use pipes to separate columns and a divider row under the header. Colons in the divider row set alignment. Tables are supported by GFM, but are not part of core CommonMark, so preview them on the platform where the document will appear.

| Format | Purpose |
|:-------|:--------|
| JSON   | Data    |
| YAML   | Config  |

For a horizontal rule, put ---, *** or ___ on a line by itself, with a blank line above it.

Escaping special characters

If a character would normally trigger formatting, put a backslash before it to show the character literally:

\*this is not italic\*

Markdown quick reference

Writing Markdown for developer projects

README files and documentation

Markdown keeps project documentation in plain text, which makes it easy to read, edit and review alongside code. Draft in the Markdown Editor with Live Preview to see how headings, lists and code blocks render before committing the file.

YAML front matter

Some static site generators read page metadata from YAML placed between --- markers at the top of a Markdown file. This section is called front matter:

---
title: "Project notes"
date: 2026-10-09
tags: [markdown, guide]
---

If your metadata is in JSON, convert it with the JSON to YAML Converter. For a broader comparison of the formats and their trade-offs, see JSON vs XML vs YAML.

Comparing edits and cleaning up repeated text

Markdown is plain text, so you can compare document versions to review exactly what changed. The Text Diff Checker can help compare two drafts before publication.

For repetitive edits, a regular expression can transform matching text. For example, this pattern and replacement turn a bare URL on a line into a Markdown link:

Find:    ^(https?://\S+)$
Replace: [$1]($1)

Test bulk replacements on a copy first. A pattern that matches more than intended can alter text outside the target lines.

Converting and reusing Markdown

Use the Markdown to PDF & HTML Converter to prepare a document for sharing as HTML or PDF. The PDF to Markdown Converter can turn a PDF into editable text, but review the result: page layout, tables and multiple columns may not map neatly back to Markdown.

Common Markdown mistakes

1. Leaving out the space after #. Write # Title, not #Title.
2. Skipping blank lines. Add a blank line before a list or table so it is not interpreted as part of the preceding paragraph.
3. Inconsistent list indentation. Use a consistent number of spaces for nested items.
4. Expecting every newline to create a line break. Use a hard-break marker or a blank line when that is the intended layout.
5. Leaving special characters unescaped. An asterisk or underscore in ordinary text can be interpreted as formatting; escape it or wrap the text in code.
6. Forgetting to close a code fence. An unclosed fence can make the rest of the document render as code.
7. Using a pipe inside a table cell without escaping it. Write \| when a literal pipe belongs in a cell.
8. Assuming extensions work everywhere. Tables, task lists and other additions vary by renderer. Preview the final document in its destination.
9. Relying on raw HTML. Some platforms limit or remove HTML inside Markdown.