Markdown for Beginners: Learn the Basics in Minutes

Welcome to the basic markdown guide. If you are drafting a GitHub readme file, writing notes in Obsidian, or formatting web pages, markdown is the most efficient language to write structured content. Since it utilizes standard keyboard symbols, you can write formatting styles without lifting your hands from the keyboard.

This tutorial outlines the core elements needed to learn markdown basics instantly.

1. What is Markdown?

Markdown is a lightweight markup language designed to make formatting text easy. Created in 2004, it allows writers to draft content using plain text characters that convert directly into clean HTML. This design ensures that raw files remain readable, even without special software.

Traditional word processors hide formatting styles inside complex binary file formats. If you open a word document in a basic text editor, you will see unreadable code. In contrast, a markdown document displays clear keyboard characters that indicate layout structure. This simplicity has made it the default formatting language for developer platforms like GitHub and knowledge bases like Obsidian.

Because the original specification left some formatting behaviors undefined, the community created standards to ensure consistency. The most important of these is **CommonMark**, which defines strict rules for basic elements. Another key variant is **GitHub Flavored Markdown (GFM)**, which adds features like task checklists, tables, and strikethroughs.

In practice, learning markdown format is a valuable skill for technical writers, software developers, and content creators. It allows you to focus on writing without getting distracted by visual formatting menus.

2. Structuring Headers

Headings organize your document structure. Create headings by adding hash markers (#) at the start of a line, followed by a space. The number of hashes determines the header level from H1 to H6.

# Level 1 Heading (H1)
## Level 2 Heading (H2)
### Level 3 Heading (H3)
#### Level 4 Heading (H4)

You must insert a space between the hash markers and your heading text. If you write ##Heading, standard parsers will display it as regular text. We recommend using Heading 1 for document titles, Heading 2 for major sections, and Heading 3 for subsections.

For search engine optimization (SEO), it is best practice to restrict your page layout to a single H1 heading tag. The H1 represents the main topic of the page, while H2 and H3 elements function as chapters or subsections under that main topic. Nesting your headers logically (e.g. going from H2 straight to H3, rather than skipping from H2 to H4) ensures that crawlers can index the thematic relationships of your text columns easily.

# Main Article Title (Only one H1)
## Section Heading (H2)
### Subsection Details (H3)
#### Nested Bullet Point Details (H4)

3. Bold and Italic Emphasis

To apply text emphasis, wrap target words inside single or double asterisks:

To make text italic, wrap it in single asterisks: *italic text* or underscores: _italic text_.
To make text bold, wrap it in double asterisks: **bold text** or double underscores: __bold text__.
To apply both styles, use triple asterisks: ***bold and italic***.

Avoid mixing asterisks and underscores in a single decoration block. For example, writing *_italic_* can cause rendering issues on older compilers. Choose one style and keep it consistent across your files.

4. Creating Bulleted and Numbered Lists

Create unordered (bulleted) lists by starting lines with hyphens (-), asterisks (*), or plus signs (+) followed by a space:

- Bullet item one
- Bullet item two
  - Nested sub-item (indent with two spaces)
  - Another nested sub-item

For ordered lists, start lines with numbers followed by a period and a space:

1. First step in instructions
2. Second step in instructions
   1. Sub-step under step two

Ensure you add a space after the list symbol. Nesting items requires indenting the line with two or four spaces so the compiler groups the elements correctly under the parent list option.

5. Writing Hyperlinks

Links insert hyperlinks directly into document bodies. Wrap the display anchor text in square brackets, and place the target URL path immediately after in parentheses:

Visit our live [Markdown Editor](/tools/markdown-editor) to practice formatting.

When writing links in markdown, you can use absolute URLs or relative file paths:

Absolute URLs: Reference full web domain links, starting with `https://` or `http://` (e.g. `[Google](https://google.com)`).
Relative Paths: Reference local directory files inside your project structure (e.g. `[Local Setup Guide](./docs/setup.md)`). This is useful in Git repositories to link between documents.

You can also add an optional tooltip title by placing the text in quotes after the URL inside the parentheses: [Docs](/docs "Open documentation"). The tooltip appears when visitors hover their mouse over the link.

6. Blockquotes & Horizontal Lines

Use blockquotes to format quote references or pullout notes. Start the line with a greater-than sign (>) followed by a space:

> This is a quote block.
> It can span multiple lines by adding the greater-than sign.

You can also nest blockquotes inside each other by using multiple greater-than signs. This is useful for formatting multi-level comment chains:

> This is the primary blockquote level.
> > This is a nested sub-level blockquote.

To separate different sections of your document visually, use a horizontal line. Create a horizontal rule by typing three or more hyphens (---) or asterisks (***) on their own line:

Section ends here.
---
New section starts here.

7. Common Mistakes Beginners Make

When learning markdown, watch out for these formatting pitfalls:

Missing blank lines between elements: Standard markdown requires a blank line between different blocks. For example, if you place a heading directly above a list without a blank line, the formatting can fail.
Missing spaces in headings: Remember to place a space after the hash characters. Writing #Title will display as raw text.
Incorrect nested indentation: When nesting sublists, align the sub-items using spaces (typically two or four spaces). Using tabs can confuse the parser, causing list items to render as code blocks.
Line Break Confusion: Pressing enter once at the end of a line does not trigger a new line in standard markdown output. To force a line break, add two spaces at the end of the line before pressing enter, or end the line with a backslash.

By practicing these basic rules in our live editor, you can learn the habits needed to draft clean, formatted documents quickly.

Frequently Asked Questions

What is markdown and why should I learn it?

Markdown is a simple plain-text markup language designed to write formatted text without using complex HTML tags or binary word processors. It is highly readable in its raw state and converts easily to HTML.

How do I bold text in markdown?

To make text bold, wrap the characters inside double asterisks, like **bold text**.

How do I add a link in markdown?

To write a link, place the display anchor text inside square brackets, followed immediately by the URL path in parentheses: [anchor text](https://example.com).

How do I create a new paragraph in markdown?

To start a new paragraph, insert a full blank line between your text blocks. Simply pressing enter once will not trigger a paragraph break in standard parsers.

Can I write standard HTML inside my markdown files?

Yes. Most markdown parsers support inline HTML elements, allowing you to use tags like <u>underline</u> or <span>color styling</span> inside plain-text files.