The Complete Beginner's Guide to Markdown

Markdown is a way of writing formatted text using plain, typed characters instead of a toolbar. Instead of clicking a "Bold" button, a word gets wrapped in asterisks. Instead of selecting a heading style from a dropdown, a line starts with a #. Once the pattern clicks, the whole system takes only a few minutes to learn, because it's small by design — a handful of symbols cover nearly everything most writing needs.

The Core Syntax

Type this	To get this
# Heading	A large, top-level heading
## Heading	A second-level heading
### Heading	A third-level heading
**bold text**	bold text
*italic text*	italic text
- item	A bullet point
1. item	A numbered list item
[text](url)	A clickable link
`code`	Inline code formatting
> quote	A blockquote

That table is, genuinely, most of what gets used in day-to-day Markdown writing. Everything below adds detail and covers less common cases, but a person who only ever uses the ten patterns above can write nearly anything.

Headings, in Practice

The number of # symbols controls the heading level — one for the largest (typically used once, for the document's title), up to six for the smallest. A space after the last # and before the text is required for the heading to render correctly:

# Main Title
## A Major Section
### A Subsection

Bold and Italic, and Combining Them

Double asterisks make text bold, single asterisks make it italic, and combining both — triple asterisks — makes text bold and italic at once:

**This is bold**
*This is italic*
***This is bold and italic***

Underscores work as an alternative to asterisks for both bold (__text__) and italic (_text_) in most Markdown implementations, though asterisks are more commonly used and slightly less prone to accidental triggering inside words that legitimately contain underscores, like variable or file names.

Lists

Unordered (bulleted) lists use a dash, asterisk, or plus sign at the start of a line, followed by a space:

- First item
- Second item
- Third item

Ordered (numbered) lists use numbers followed by a period. Markdown generally re-numbers these automatically when rendered, so the actual numbers typed don't need to be sequential — writing 1. for every line still produces a correctly numbered list in most renderers:

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

Nested lists (a sub-list within a list item) are created by indenting the nested items, typically with two or four spaces, depending on the specific Markdown flavor being used.

Links and Images

A link uses square brackets for the visible text, immediately followed by parentheses containing the URL:

[ClearText Editor](https://cleartexteditor.com)

Images use nearly identical syntax, with an exclamation point in front — the bracket text becomes the image's alt text rather than clickable link text:

![A description of the image](image-url.jpg)

Code: Inline and in Blocks

A single backtick on either side of a word or phrase creates inline code formatting — useful for referencing a command, a variable name, or a filename within a normal sentence: `git commit` renders as git commit.

For a multi-line block of code, three backticks on their own line, before and after the code, create a fenced code block:

```
function greet() {
  console.log("hello");
}
```

Many Markdown renderers support adding a language name immediately after the opening three backticks (```javascript, for instance) to enable syntax highlighting specific to that language.

Blockquotes

A right angle bracket at the start of a line creates a blockquote, typically rendered with indentation and a visual marker (often a left border), used for quoting external text or setting a passage visually apart from the surrounding content:

> This is a quoted passage,
> visually set apart from the rest.

The One Habit Worth Building Early: Blank Lines Matter

Markdown generally treats a single line break as no break at all when rendering — two lines of text typed one after another, with no blank line between them, often render as a single continuous paragraph. A genuine paragraph break requires an actual blank line between the two blocks of text. This is the single most common source of "why isn't this formatting correctly" confusion for people new to Markdown, and it's worth internalizing early: when in doubt, add a blank line.

Nearly every Markdown rendering surprise a beginner runs into traces back to one of two things: a missing blank line between blocks, or a missing space after a symbol like # or -. Both are easy habits to build once they're understood, and most confusion disappears once they're second nature.

Where This Gets Used

The syntax above works, largely unchanged, across GitHub, GitLab, Reddit, Discord, Slack (with minor variations), static site generators, note-taking apps like Notion and Obsidian, and most developer documentation tools. This consistency is one of Markdown's biggest practical advantages — learning it once means it's usable almost everywhere formatted text is needed, a point covered in more depth in our post on why developers love Markdown.

Practicing Without a Specific Destination

The fastest way to get comfortable with Markdown syntax is writing something short with it directly — a note, a list, a short piece of documentation — rather than reading through the full syntax reference in one sitting. ClearMark provides a live preview alongside the Markdown source, so the connection between typed syntax and rendered output is visible immediately, which speeds up the learning process considerably compared to writing blind and checking the result separately afterward.

When Formatted Text Needs to Leave Markdown

Markdown's plain-text nature is ideal for writing and version control, but eventually most Markdown content needs to become something else — an HTML page, a section of a larger formatted document, content pasted into an editor that doesn't understand Markdown syntax directly. Converting Markdown to HTML (or the reverse) is covered in detail in our post on how to convert Markdown to HTML without breaking formatting.

---

Markdown's entire learning curve is really just the ten patterns covered here, plus the habit of using blank lines between paragraphs. Everything past that point is refinement and occasional edge cases — the core syntax is genuinely small enough to hold in memory after a single real writing session, which is a large part of why it spread as widely as it did.