Markdown Syntax: The Complete Reference

March 10, 2026 · 5 min read

Understanding Markdown Syntax

Markdown is favored for its simplicity, allowing users to format text using just a plain text editor. This lightweight markup language is ubiquitous in environments where raw HTML or rich text editors are unsuitable or unavailable. It's the default choice for documentation on platforms like GitHub, Reddit comments, and static site generators. This article breaks down Markdown into its components, providing insights and practical techniques to maximize its use.

Basic Formatting Techniques

Markdown offers straightforward text manipulation. It's essential to master these for creating clean, readable documents.

Text Emphasis and Inline Code

• Bold Text: Use two asterisks (**) or underscores (__) to emphasize text with bold styling. For instance, **important** renders important.
• Italic Text: Italics are achieved with one asterisk (*) or underscore (_), useful for phrases, foreign language, or citations: *italicized* becomes italicized.
• Strikethrough: Apply two tildes (~~) to show what has been removed or altered: ~~removed~~ results in removed.
• Inline Code: Backticks (`) encapsulate inline code snippets. Example: `let x = 5;` for JavaScript inline code.

Headings for Structure and Clarity

Headings help organize and prioritize content; Markdown uses # symbol efficiently:

# Primary Header
## Secondary Header
### Tertiary Header
#### Quaternary Header
##### Quinary Header
###### Senary Header

Constrain # usage for section titles to maintain hierarchy. Avoid using the main header (<h1>) inside a document, typically reserved for its title.

Organizing Content with Lists

Lists enhance the readability and organization of information. Markdown supports unordered and ordered lists.

Creating Unordered Lists

To make unordered lists, start lines with *, -, or +:

* Apples
- Oranges
+ Bananas

Indented items can form nested lists:

* Fruit
  * Apple
  * Banana
* Vegetables
  * Carrot

Using Ordered Lists

Introduce sequence with ordered lists, prefacing each item with a number and a period:

1. Install software
2. Configure settings
3. Run application

This systematic approach is crucial for steps, priorities, or rankings.

Incorporating Links and Images

Hyperlinks for External Sources

Links in Markdown are straightforward, using brackets and parentheses:

[Visit GitHub](https://github.com)

For reusable references, define a label and URL separately:

[GitHub]: https://github.com
Learn more at [GitHub]

Embedding Images

Images utilize similar syntax with an exclamation mark:

![Logo](logo.png)

Ensure correct path referencing, preferably hosted online, and consider base64 text for embedding images directly.

Advanced Markdown Formatting

Code Blocks

For multiple lines of code, use triple backticks. Add a language for syntax highlighting:

```javascript
function greet() {
  console.log("Hello, World!");
}

Effectively display complex code for documentation or tutorials.

Table Construction

Markdown tables organize data neatly:

| Name     | Age |
|----------|-----|
| John Doe | 28  |
| Jane Doe | 32  |

Align columns using colons (:---:, etc.). Extract data from CSV using a csv parser for easy conversion.

Utilizing Blockquotes and Task Lists

Blockquotes for Highlighting

Draw attention using blockquotes:

> This is a quote.

Nest quotes for layered emphasis:

> First level
> > Second level

Task Lists for Management

Create task lists with checkboxes:

- [x] Review pull request
- [ ] Deploy update

Interactive on GitHub, these lists are vital for tracking progress.

Boosting Efficiency with Markdown Tools

• Use an HTML stripper to convert HTML to Markdown format easily.
• A character counter tracks text length; practical for platform constraints.
• Convert images using base64 text for embedding directly in Markdown files.
• Employ find and replace for swift edits across extensive texts.
• Leverage a csv parser for quick conversion of tabular data.

Key Takeaways

• Markdown is simple yet effective for text formatting.
• Use headings and lists to organize content heuristically.
• Hyperlinks and images enrich your documents by inclusion of external resources.
• Code blocks and tables effectively present complex data.
• Task lists integrate seamlessly into project management workflows.
• Quotes are useful for emphasizing significant ideas or statements.

Refine your Markdown proficiency further with our Markdown Editor.

Frequently Asked Questions

What's the difference between Markdown flavors?

Original Markdown (by John Gruber) is minimal. CommonMark standardized the spec. GitHub Flavored Markdown (GFM) adds tables, task lists, and strikethrough. Other flavors (Markdown Extra, MultiMarkdown) add footnotes, definition lists, and more. Most modern tools support GFM or CommonMark.

Can I use HTML inside Markdown?

Yes—Markdown allows inline HTML for anything it doesn't support natively (like details, video, or custom styling). Just write the HTML directly in your Markdown file. Some parsers restrict this for security (like GitHub comments), but most static site generators allow it.

How do I escape Markdown special characters?

Use a backslash before special characters to escape them. For example, prefix an asterisk with backslash to prevent italic formatting. Characters that commonly need escaping include backslash, asterisk, underscore, curly braces, square brackets, parentheses, hash, plus, minus, dot, and exclamation mark. Inside code blocks or inline code, you don't need to escape anything.

Why isn't my Markdown rendering correctly?

Common issues: (1) Missing blank lines around blocks (lists, code blocks need blank lines before/after), (2) Inconsistent indentation (use 4 spaces or 1 tab for nested lists), (3) Flavor differences (your parser might not support the syntax you're using). Test with a different parser or check the docs for your specific flavor.