Mastering Markdown Syntax

What Is Markdown?

Markdown is a lightweight markup language created by John Gruber in 2004. Its goal is simple: let you write content using plain text formatting that's easy to read and write, then convert it to structurally valid HTML. Unlike HTML, Markdown doesn't require you to remember angle brackets, closing tags, or attributes. A heading is just a line starting with #, bold text is wrapped in **, and links are written as [text](url).

Today, Markdown is used everywhere: GitHub README files, documentation sites, blogging platforms (Ghost, Hugo, Jekyll), note-taking apps (Obsidian, Notion), messaging platforms (Slack, Discord), and even email clients. Learning Markdown is one of the highest-ROI skills for anyone who writes digital content.

Headings

Headings use hash symbols. The number of hashes determines the heading level:

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Always put a space after the hash. Most style guides recommend using only one H1 per document (your title), then H2 for major sections and H3 for subsections. Skipping levels (e.g., going from H2 to H4) hurts accessibility and SEO.

Emphasis: Bold and Italic

Markdown gives you two levels of emphasis:

*italic text* or _italic text_
**bold text** or __bold text__
***bold and italic*** or ___bold and italic___
~~strikethrough~~

The convention is to use asterisks (*) rather than underscores because underscores can behave unexpectedly in the middle of words. Strikethrough (~~) is a GitHub-Flavored Markdown (GFM) extension, not part of the original CommonMark spec.

Lists

Unordered lists use dashes, asterisks, or plus signs. Ordered lists use numbers followed by periods:

- Item one
- Item two
  - Nested item (indent 2 spaces)
  - Another nested item

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

For ordered lists, the actual numbers don't matter — Markdown will auto-number them sequentially. Many writers use 1. for every item so reordering doesn't require renumbering. Task lists use - [ ] for unchecked and - [x] for checked items (GFM extension).

Links and Images

Links follow the pattern [display text](url). Images are the same but with an exclamation mark prefix:

[Visit Benrio](https://benrio.app)
[Link with title](https://example.com "Hover text")

![Alt text for image](image-url.png)
![Screenshot](./screenshot.png "Optional caption")

You can also use reference-style links to keep your text readable when you have many URLs. Define references at the bottom of your document: [1]: https://example.com and reference them inline as [link text][1].

Code: Inline and Blocks

Inline code uses single backticks. Code blocks use triple backticks (fenced code blocks) with an optional language identifier for syntax highlighting:

Inline: `const x = 42`

Fenced block:
```javascript
function greet(name) {
  return `Hello, ${name}!`;
}
```

Common language identifiers include javascript, python, html, css, bash, json, typescript, and sql. The syntax highlighting depends on the renderer — GitHub, VS Code, and most documentation platforms support hundreds of languages.

Blockquotes

Prefix lines with > to create blockquotes. They can be nested and can contain other Markdown elements:

> This is a blockquote.
> It can span multiple lines.
>
> > This is a nested blockquote.
>
> - You can include lists
> - Inside blockquotes

Tables

Tables use pipes and dashes. The alignment row (second row) controls column alignment using colons:

| Feature    | Supported | Notes         |
|:-----------|:---------:|--------------:|
| Left align | Center    | Right align   |
| Headings   | Yes       | All 6 levels  |
| Lists      | Yes       | Nested too    |
| Code       | Yes       | Fenced blocks |

Tables are a GFM extension. The columns don't need to line up perfectly in your source — the renderer handles alignment. For complex tables, consider using HTML directly within your Markdown document.

Horizontal Rules

Create a horizontal line (thematic break) with three or more dashes, asterisks, or underscores on their own line:

---
***
___

Advanced: Footnotes, Math, and Diagrams

Extended Markdown flavors support additional features. GitHub supports footnotes with [^1] syntax. Many platforms support LaTeX math with $inline$ and $$block$$ delimiters. Mermaid diagrams can be embedded in fenced code blocks with the mermaid language identifier on platforms like GitHub and Notion.

Best Practices

• One sentence per line — Makes diffs cleaner in version control and is easier to rearrange.
• Blank lines between elements — Always leave a blank line before and after headings, lists, code blocks, and blockquotes.
• Consistent list markers — Pick dashes or asterisks and stick with one throughout your document.
• Alt text on images — Always include descriptive alt text for accessibility and SEO.
• Reference-style links for long documents — Keeps paragraphs readable when URLs are long.
• Use a linter — Tools like markdownlint catch inconsistencies and enforce style rules automatically.

CommonMark vs GitHub-Flavored Markdown

CommonMark is the standardized specification of Markdown that aims to resolve ambiguities in Gruber's original syntax. GitHub-Flavored Markdown (GFM) extends CommonMark with tables, task lists, strikethrough, autolinks, and fenced code blocks. Most modern renderers (including the one in our Markdown Previewer tool) support GFM features.