Skip to content

Basic Syntax


  • Get Started
    Go to

    An overview of Markdown, why to use it, how it works, and the best way to get started.

  • Cheat Sheet
    Go to

    A quick reference of all the Markdown elements for fast lookups while you're writing.

  • Basic Syntax
    Go to

    The foundational elements outlined in the original John Gruber design document.

  • Extended Syntax
    Go to

    Advanced features like tables, code blocks, and task lists not found in basic MD.

  • Hacks
    Go to

    Creative ways to extend Markdown functionality for more complex document needs.

  • Tools
    Go to

    A comprehensive list of applications, editors, and libraries that support Markdown.

  • The Book
    Go to

    The Markdown Guide is also available as a paperback and digital book for deep learning.

  • Markdown Guide
    Go to

    The primary resource for learning the syntax, tools, and best practices of Markdown.

  • MkDocs-Material
    Return to

    Back to the root documentation.

Markdown

The Markdown elements outlined in the original design document.

NB: Nearly all Markdown applications support the basic syntax as outlined in
the original Markdown design document.

There are a few minor variations, as well as discrepancies between Markdown
processors — Most of these are noted inline wherever possible.

Headings⚓︎

To create a heading, add number signs (#) in front of a word or phrase. The number of number signs you use should correspond to the heading level. For example, to create a heading level three (<h3>), use three number signs (e.g., ### My Header).

HTML Code for the table below 
<div class="isolated-table-container">
  <style>
    /* Use CSS Variables instead of hardcoded colors for dynamic theming */
    .isolated-table-container .table.table-bordered {
      border-collapse: collapse;
      width: 100%;
      max-width: 800px;
      margin: 20px auto;
      /* Use theme default border color */
      border: 1px solid var(--md-default-fg-color--light); 
      font-size: 16px;
      /* Default background color */
      background-color: var(--md-default-bg-color); 
      /* Default text color */
      color: var(--md-default-fg-color);
    }
    .isolated-table-container .table.table-bordered th,
    .isolated-table-container .table.table-bordered td {
      /* Use theme default border color */
      border: 1px solid var(--md-default-fg-color--light); 
      padding: 8px;
      text-align: left;
    }
    .isolated-table-container .table.table-bordered thead th {
      /* Use primary theme color for header background */
      background-color: var(--md-primary-fg-color); 
      font-weight: bold;
      /* Ensure header text is readable against primary color */
      color: var(--md-primary-bg-color); 
    }
    .isolated-table-container .table.table-bordered tbody tr:nth-child(odd) {
        /* Add some striping using a slightly different background color variable */
        background-color: var(--md-default-bg-color--light);
    }
    .isolated-table-container .table.table-bordered a {
      /* Use theme accent color for links */
      color: var(--md-accent-fg-color); 
      text-decoration: underline;
    }
  </style>

  <!-- Your original HTML table code starts here -->
  <table class="table table-bordered">
    <thead class="thead-light">
      <tr>
        <th>Markdown</th>
        <th>HTML</th>
        <th>Rendered Output</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><code class="highlighter-rouge"># Heading level 1</code></td>
        <td><code class="highlighter-rouge">&lt;h1&gt;Heading level 1&lt;/h1&gt;</code></td>
        <td><h1 class="no-anchor" data-toc-skip="" id="heading-level-1">Heading level 1</h1></td>
      </tr>
      <tr>
        <td><code class="highlighter-rouge">## Heading level 2</code></td>
        <td><code class="highlighter-rouge">&lt;h2&gt;Heading level 2&lt;/h2&gt;</code></td>
        <td><h2 class="no-anchor" data-toc-skip="" id="heading-level-2">Heading level 2</h2></td>
      </tr>
      <tr>
        <td><code class="highlighter-rouge">### Heading level 3</code></td>
        <td><code class="highlighter-rouge">&lt;h3&gt;Heading level 3&lt;/h3&gt;</code></td>
        <td><h3 class="no-anchor" data-toc-skip="" id="heading-level-3">Heading level 3</h3></td>
      </tr>
      <tr>
        <td><code class="highlighter-rouge">#### Heading level 4</code></td>
        <td><code class="highlighter-rouge">&lt;h4&gt;Heading level 4&lt;/h4&gt;</code></td>
        <td><h4 class="no-anchor" id="heading-level-4">Heading level 4</h4></td>
      </tr>
      <tr>
        <td><code class="highlighter-rouge">##### Heading level 5</code></td>
        <td><code class="highlighter-rouge">&lt;h5&gt;Heading level 5&lt;/h5&gt;</code></td>
        <td><h5 class="no-anchor" id="heading-level-5">Heading level 5</h5></td>
      </tr>
      <tr>
        <td><code class="highlighter-rouge">###### Heading level 6</code></td>
        <td><code class="highlighter-rouge">&lt;h6&gt;Heading level 6&lt;/h6&gt;</code></td>
        <td><h6 class="no-anchor">Heading level 6</h6></td>
      </tr>
    </tbody>
  </table>
</div>
Markdown HTML Rendered Output
# Heading level 1 <h1>Heading level 1</h1>

Heading level 1
## Heading level 2 <h2>Heading level 2</h2>

Heading level 2
### Heading level 3 <h3>Heading level 3</h3>

Heading level 3
#### Heading level 4 <h4>Heading level 4</h4>

Heading level 4
##### Heading level 5 <h5>Heading level 5</h5>
Heading level 5
###### Heading level 6 <h6>Heading level 6</h6>
Heading level 6

Table converted from html to markdown as a ref.⚓︎

Table converted from html to markdown as a ref. 
| Markdown | HTML | Rendered Output |
| :--- | :--- | :--- |
| `# Heading level 1` | `<h1>Heading level 1</h1>` | <h1>Heading level 1</h1> |
| `## Heading level 2` | `<h2>Heading level 2</h2>` | <h2>Heading level 2</h2> |
| `### Heading level 3` | `<h3>Heading level 3</h3>` | <h3>Heading level 3</h3> |
| `#### Heading level 4` | `<h4>Heading level 4</h4>` | <h4>Heading level 4</h4> |
| `##### Heading level 5` | `<h5>Heading level 5</h5>` | <h5>Heading level 5</h5> |
| `###### Heading level 6` | `<h6>Heading level 6</h6>` | <h6>Heading level 6</h6> |
Markdown HTML Rendered Output
# Heading level 1 <h1>Heading level 1</h1>

Heading level 1
## Heading level 2 <h2>Heading level 2</h2>

Heading level 2
### Heading level 3 <h3>Heading level 3</h3>

Heading level 3
#### Heading level 4 <h4>Heading level 4</h4>

Heading level 4
##### Heading level 5 <h5>Heading level 5</h5>
HEADING LEVEL 5
###### Heading level 6 <h6>Heading level 6</h6>
Heading level 6

Alternate Syntax⚓︎

Alternatively, on the line below the text, add any number of == characters for heading level 1 or -- characters for heading level 2.

Alternate Syntax Reference⚓︎

HTML Code for the table below 
<div class="isolated-table-container">
  <style>
    /* Use CSS Variables instead of hardcoded colors for dynamic theming */
    .isolated-table-container .table.table-bordered {
      border-collapse: collapse;
      width: 100%;
      max-width: 800px;
      margin: 20px auto;
      border: 1px solid var(--md-default-fg-color--light); 
      font-size: 16px;
      background-color: var(--md-default-bg-color); 
      color: var(--md-default-fg-color);
    }
    .isolated-table-container .table.table-bordered th,
    .isolated-table-container .table.table-bordered td {
      border: 1px solid var(--md-default-fg-color--light); 
      padding: 8px;
      text-align: left;
    }
    .isolated-table-container .table.table-bordered thead th {
      background-color: var(--md-primary-fg-color); 
      font-weight: bold;
      color: var(--md-primary-bg-color); 
    }
    .isolated-table-container .table.table-bordered tbody tr:nth-child(odd) {
        background-color: var(--md-default-bg-color--light);
    }
    .isolated-table-container .table.table-bordered a {
      color: var(--md-accent-fg-color); 
      text-decoration: underline;
    }
  </style>

  <table class="table table-bordered">
    <thead class="thead-light">
      <tr>
        <th>Markdown</th>
        <th>HTML</th>
        <th>Rendered Output</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td><code class="highlighter-rouge">Heading level 1<br>===============</code></td>
        <td><code class="highlighter-rouge">&lt;h1&gt;Heading level 1&lt;/h1&gt;</code></td>
        <td><h1 class="no-anchor" data-toc-skip="" id="heading-level-1-1">Heading level 1</h1></td>
      </tr>
      <tr>
        <td><code class="highlighter-rouge">Heading level 2<br>---------------</code></td>
        <td><code class="highlighter-rouge">&lt;h2&gt;Heading level 2&lt;/h2&gt;</code></td>
        <td><h2 class="no-anchor" data-toc-skip="" id="heading-level-2-1">Heading level 2</h2></td>
      </tr>
    </tbody>
  </table>
</div>
Table converted from html to markdown as a ref. 
| Markdown | HTML | Rendered Output |
| :--- | :--- | :--- |
| `Heading level 1`<br>`===============` | `<h1>Heading level 1</h1>` | <h1>Heading level 1</h1> |
| `Heading level 2`<br>`---------------` | `<h2>Heading level 2</h2>` | <h2>Heading level 2</h2> |
Markdown HTML Rendered Output
Heading level 1
===============		 <h1>Heading level 1</h1>

Heading level 1
Heading level 2
---------------		 <h2>Heading level 2</h2>

Heading level 2

Heading Best Practices⚓︎

Markdown applications don’t agree on how to handle a missing space between the number signs (#) and the heading name. For compatibility, always put a space between the number signs and the heading name.

Paragraphs⚓︎

To create paragraphs, use a blank line to separate one or more lines of text.

Heading Best Practices⚓︎

Markdown applications don’t agree on how to handle a missing space between the number signs (#) and the heading name. For compatibility, always put a space between the number signs and the heading name.

Paragraphs⚓︎

To create paragraphs, use a blank line to separate one or more lines of text.

Paragraph Best Practices

Unless the paragraph is in a list, don’t indent paragraphs with spaces or tabs.

  1. List item one.

List item one continued with a second paragraph followed by an indented block.

$ ls *.sh
$ mv *.sh ~/tmp

List item continued with a third paragraph.

  1. List item two continued with an open block.

This paragraph is part of the preceding list item.

  • a. This list is nested and does not require explicit item continuation.

    This paragraph is part of the preceding list item.

  • b. List item b.

This paragraph belongs to item two of the outer list.