Markdown Syntax Reference

This is a definitive guide to the syntax of Markdown as used in documentation, code comments, issue tracking, and content authoring. It covers the full set of features that engineers use daily, from simple formatting to complex structures. Use this reference when writing or debugging Markdown, especially when syntax behaves unexpectedly or when migrating between tools.

Basic Text Formatting

Emphasis and Strong Text

Use * or _ for *emphasis* and or __ for strong text**. Both are interchangeable, but consistency matters.

*Italic text*
_Italic text_
**Bold text**
__Bold text__
***Bold italic*** — combines both

The * and _ delimiters must be balanced. Unmatched delimiters fail silently:

*This is italic, but this is not* and *this is*

Here, only “This is italic, but this is not” is italicized. The second * starts a new emphasis, but the closing * is lost.

Line Breaks and Paragraphs

A blank line (one or more empty lines) between text creates a new paragraph. Use (two spaces at end of line) for a line break within a paragraph.

This is the first paragraph.

This is the second paragraph.

This line ends with two spaces  
and this is the continuation.

The is crucial: single space fails. When rendering in GitHub, GitLab, or Jupyter, missing the trailing spaces causes tight, unbroken text.

Blockquotes

Prefix lines with >. Multiple levels use multiple >.

> This is a blockquote.
>
> > Nested blockquote.
> >
> > > Deeper nested.
>
> A second paragraph in the blockquote.

Blockquotes can mix with other elements:

> at start of line
> (space after >) for content
> anywhere on line, including inside lists

When nesting, a single > does not create a new level unless followed by a space or another >. The indentation of the content matters.

Lists

Unordered Lists

Use -, *, or + for bullet points. All are equivalent.

- Item one
- Item two
- Item three

Nested lists use indentation (at least one space per level). The first level starts at column 1; subsequent levels align with the parent.

- First level
  - Second level
  - Second level, continued
    - Third level
    - Third level, also continued
- Back to first level

Indentation must be consistent. A mix of tabs and spaces causes inconsistent nesting. Use spaces only.

Ordered Lists

Use numbers followed by a period: 1., 2., etc. The actual numbers do not need to be sequential.

1. First item
2. Second item
3. Third item

But this is valid:

1. First item
1. Second item
1. Third item

The rendering is identical. Use this to force a specific numbering across sections.

List Items with Multiple Paragraphs

A list item can contain multiple paragraphs, code blocks, or other elements.

- First item
  This is a paragraph.

  This is another paragraph.

  Here is a code block:
  ```python
  def hello():
      return "world"

Second item

With a list inside:

Nested item
Another nested item


The key is that a blank line between elements starts a new block. The first paragraph is attached to the list item, and subsequent blocks are nested.

## Code Blocks

### Fenced Code Blocks
Use triple backticks (```` ``` ````) to create a code block. Optionally, specify the language after the opening backticks.

```markdown
```python
def factorial(n):
    if n <= 1:
        return 1
    return n * factorial(n - 1)

{
  "name": "Alice",
  "age": 30
}

$ git add .
$ git commit -m "Initial commit"
$ git push origin main

The language name enables syntax highlighting. Use standard language names: js, ts, yaml, toml, sql, diff, sh, json, html, xml.

Inline Code

Wrap text in single backticks: ` code `.

Use `git commit -m "Message"` to record changes.

The content inside the backticks is literal. Spaces, newlines, and special characters are preserved.

Code Block Indentation

For indented code blocks (four spaces), the content must be indented by exactly four spaces from the left margin.

    def hello():
        print("Hello, world!")
    print("Done.")

If any line has three spaces, it is not part of the code block. The first line must be at column 4 or greater.

Headers

Setext Headers

Use underlines of = or - below text.

This is a top-level header
===========================

This is a second-level header
------------------------------

The underline must be at least as long as the header text. A longer underline is acceptable but not required.

Atx Headers

Use # for level 1 to ###### for level 6.

# Level 1
## Level 2
### Level 3
#### Level 4
##### Level 5
###### Level 6

The number of # signs determines the level. The # can be immediately followed by a space or a newline.

#Header
# Header

Both are valid, but #Header is not equivalent to # Header if the space is missing.

Links and Images

Inline Links

Use text syntax.

[Google](https://www.google.com)

The URL can be absolute or relative. Use https://, http://, or // for protocol-relative links.

For a link with a title, use text.

[GitHub](https://github.com "The best place for code")

The title is optional. Omitting it causes the title to be "".

Reference Links

Use [text][id] for reference links, with definitions elsewhere.

[Google][google]
[GitHub][github]

[google]: https://www.google.com
[github]: https://github.com

The definition can appear anywhere after the reference. The reference and definition do not need to be in order.

Image Syntax

Use !alt text for images.

![Logo](/images/logo.png)

Optional: add a title.

![Logo](/images/logo.png "Company Logo")

The alt text is required. The url can be relative or absolute. Use ! at start of line for a standalone image.

![](https://example.com/image.jpg)

Relative Paths and Anchors

Paths in links and images are relative to the Markdown file. Use ./, ../, and / consistently.

[Docs](./docs/index.md)
[Parent](../README.md)
[External](https://example.com/api/v1)
[Anchor](#section-1)

Anchors can be in the same document: #section-1, or across documents: path/to/file.md#section.

Tables

Basic Tables

Use pipes (|) and dashes (-) to define tables.

| Name  | Age | City       |
|-------|-----|------------|
| Alice | 30  | New York   |
| Bob   | 25  | San Francisco |

The header row must be separated from content by a row of dashes. The number of dashes must be at least as long as the longest header cell.

Alignment

Add colons (:) in the separator row to align columns.

| Left  | Centered  | Right  |
|:------|:---------:|-------:|
| A     | B         | C      |
| D     | E         | F      |

:-- aligns left
:-: aligns center
--: aligns right

Alignment applies to all cells in that column.

Multi-line Cells

A cell can span multiple lines.

| Feature         | Description                      |
|-----------------|----------------------------------|
| Authentication  | Secure login with tokens and     |
|                 | multi-factor support.            |
| API             | RESTful endpoints with versioning. |

The blank lines between rows are preserved. Use consistent indentation for content.

Inline HTML

Mixed Markdown and HTML

You can mix Markdown and HTML freely. HTML tags are parsed and rendered as-is.

<h1>Project Overview</h1>

<p>This is a <strong>Markdown</strong> document with <em>inline HTML</em>.</p>

<div class="highlight">
  <pre><code class="language-python">def main():
    print("Hello")
</code></pre>
</div>

HTML tags can be nested with Markdown. The nesting is preserved.

Escaping HTML

When you need raw HTML, use  for comments.

<!-- This section is generated by CI -->
<div class="generated">
  <ul>
    <li>Item 1</li>
    <li>Item 2</li>
  </ul>
</div>

HTML blocks can include Markdown inside.

<article>
  <h2>Release Notes</h2>
  <p>Version 1.2.0 includes:</p>
  <ul>
    <li>Feature X</li>
    <li>Bug fixes</li>
  </ul>
  <p>See <a href="/changelog">full changelog</a>.</p>
</article>

Special Features

Horizontal Rules

Use ---, ***, or ___ for horizontal rules.

---
***
___

All three are equivalent. The content can be mixed.

Start of section
---

This is a divider.

The rule spans the full width.

Abbreviations and Definitions

Use abbr and definition list syntax.

*[HTML]: HyperText Markup Language
*[API]: Application Programming Interface

The **HTML** document was generated by the **API**.

The *[key]: definition syntax defines abbreviations. Use *[key] anywhere to expand.

Footnotes

Use [^1] for a footnote reference, and [^1]: for the definition.

This is a sentence with a footnote[^1].

[^1]: This is the first footnote. It can contain multiple paragraphs.

    Additional content in the footnote.

Footnotes can span multiple paragraphs and include other Markdown.

Task Lists

Use - [ ] and - [x] for task lists.

- [x] Implement login
- [ ] Add user profile
- [ ] Write tests
- [x] Deploy to staging

The checkboxes are rendered as <input type="checkbox">. The [ ] and [x] are parsed exactly. Use ✓ or × for custom icons.

Common Pitfalls

Misaligned Headers and Lists

A list item with a header inside requires correct indentation:

- Item one
  ## Subsection
  Content below

The ## Subsection must be at least one space indented from the list item. If it starts at column 1, it becomes a top-level header outside the list.

Code Block Continuation

When a code block spans multiple sections, ensure the opening backticks are not indented.

    This is a code block
    with multiple lines.

    But this is a separate code block.

The first block is indented, but the second is not. Use (two spaces) before the second code block for proper nesting.

Unescaped Characters

Backticks, asterisks, and underscores are special. To include them literally, escape with backslash:

`This is a \`code\` block`

Use \\, \$, \*, \+, etc., for escaping.

Inline Code in Lists

Inline code inside a list must be properly indented.

- Use `git commit` to save changes.
- Run `npm install` after adding dependencies.

The git commit and npm install are rendered correctly. But if the list item is indented, the code block may fail.

Missing Blank Lines

A missing blank line between a paragraph and a code block causes the code block to be part of the paragraph.

This is a paragraph.

```python
def hello():
    print("world")

This is a second paragraph.


The `python` code block is not a separate block. The `print("world")` is part of the first paragraph.

### Overlapping Syntax
When multiple syntaxes overlap, parsing order matters.

```markdown
- [x] **Task 1**: `git commit -m "First commit"`

Here:

Task 1 is strong text
[x] is a task list item
` git commit -m "First commit" ` is inline code

All are parsed correctly. But if the git commit includes a * or _, the inner syntax must be escaped.

- [x] **Task 1**: `git commit -m "First commit"`

The First commit is italicized. The git commit is not. To fix:

- [x] **Task 1**: `git commit -m "First commit"`

The m in commit is italicized. Use m\ or m to prevent this.

Nested Blockquotes and Lists

When nesting blockquotes and lists, alignment and blank lines matter.

> - Item one
>   - Sub-item
> - Item two

The Sub-item must be indented with at least one space. If it is not, it is not nested.

Image and Link Syntax Confusion

Confusing !alt with text leads to images that are links.

![Logo](/img/logo.png)

This renders an image. But:

[Logo](/img/logo.png)

This renders a link to the image.

Use !Logo for an image, and Logo for a link.

Use !Logo for a clickable image with a title.

Conclusion

This reference covers the full breadth and depth of Markdown syntax as used by engineers. It captures the subtle but critical details that cause silent failures across systems. Use this as a definitive guide when writing, reviewing, or debugging Markdown content.

This page was rewritten on 10 October 2026. It replaced a templated version that was not specific to its own title. How these pages are written and checked. If anything here is wrong, tell us at [email protected] and we will correct it.