THEJORD LogoTHEJORD
← ← Back to Blog🇮🇹Leggi in Italiano

Markdown to HTML: Complete Syntax with Examples

THEJORD Team••1 min read
markdownhtmldocumentationtutorialtools

All Markdown syntax: headings, lists, links, images, tables, code blocks. Complete guide.

Markdown to HTML: Complete Syntax with Examples

Introduction to Markdown

Markdown is a lightweight markup language created by John Gruber in 2004. It allows you to write formatted content using plain text syntax that's easy to read and write. Markdown has become the de facto standard for documentation, README files, blog posts, and note-taking applications.

This comprehensive guide covers all Markdown syntax from basic formatting to advanced features, with practical examples showing how each element converts to HTML.

Basic Text Formatting

Headings

Create headings using hash symbols (#). The number of hashes determines the heading level:

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

Converts to:

<h1>Heading 1</h1>
<h2>Heading 2</h2>
<h3>Heading 3</h3>
<h4>Heading 4</h4>
<h5>Heading 5</h5>
<h6>Heading 6</h6>

Emphasis

Add emphasis to text using asterisks or underscores:

*italic* or _italic_
**bold** or __bold__
***bold and italic*** or ___bold and italic___
~~strikethrough~~

HTML output:

<em>italic</em>
<strong>bold</strong>
<strong><em>bold and italic</em></strong>
<del>strikethrough</del>

Paragraphs and Line Breaks

Paragraphs are separated by blank lines. For a line break within a paragraph, end a line with two spaces or use the <br> tag:

This is the first paragraph.

This is the second paragraph.

This line ends with two spaces
to create a line break.

Lists

Unordered Lists

Create bullet lists using asterisks, plus signs, or hyphens:

* Item one
* Item two
  * Nested item
  * Another nested item
* Item three

- Alternative syntax
- Works the same way

Converts to:

<ul>
  <li>Item one</li>
  <li>Item two
    <ul>
      <li>Nested item</li>
      <li>Another nested item</li>
    </ul>
  </li>
  <li>Item three</li>
</ul>

Ordered Lists

Use numbers followed by periods for numbered lists:

1. First item
2. Second item
3. Third item
   1. Nested numbered item
   2. Another nested item

The actual numbers don't matter—Markdown renumbers automatically:

1. First
1. Second
1. Third

Still produces a properly numbered list (1, 2, 3).

Task Lists (GitHub Flavored Markdown)

Create interactive checklists:

- [x] Completed task
- [ ] Incomplete task
- [ ] Another todo item

Links and Images

Inline Links

Create links using square brackets for text and parentheses for URL:

[Link text](https://example.com)
[Link with title](https://example.com "Title text")

HTML output:

<a href="https://example.com">Link text</a>
<a href="https://example.com" title="Title text">Link with title</a>

Reference Links

For cleaner documents, use reference-style links:

Here's a [link to Google][1] and [another link][google].

[1]: https://google.com
[google]: https://google.com "Google Homepage"

Images

Images use similar syntax with an exclamation mark prefix:

![Alt text](image-url.jpg)
![Alt text](image-url.jpg "Image title")

Reference style:
![Alt text][logo]

[logo]: /images/logo.png "Logo"

HTML output:

<img src="image-url.jpg" alt="Alt text">
<img src="image-url.jpg" alt="Alt text" title="Image title">

Linked Images

Combine links and images:

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

Code

Inline Code

Wrap code in backticks:

Use the `console.log()` function for debugging.

Output: Use the console.log() function for debugging.

Code Blocks

Use triple backticks for multi-line code blocks, optionally specifying the language:

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

```python
def greet(name):
    return f"Hello, {name}!"
```

HTML output with syntax highlighting class:

<pre><code class="language-javascript">
function greet(name) {
  return `Hello, ${name}!`;
}
</code></pre>

Indented Code Blocks

Alternatively, indent code by 4 spaces:

    function example() {
        return true;
    }

Blockquotes

Use greater-than symbols for quotations:

> This is a blockquote.
>
> It can span multiple paragraphs.
>
> > Nested blockquotes work too.

HTML output:

<blockquote>
  <p>This is a blockquote.</p>
  <p>It can span multiple paragraphs.</p>
  <blockquote>
    <p>Nested blockquotes work too.</p>
  </blockquote>
</blockquote>

Horizontal Rules

Create horizontal lines with three or more hyphens, asterisks, or underscores:

---

***

___

All produce: <hr>

Tables (GitHub Flavored Markdown)

Create tables using pipes and hyphens:

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Control column alignment with colons:

| Left | Center | Right |
|:-----|:------:|------:|
| L    |   C    |     R |

HTML output:

<table>
  <thead>
    <tr>
      <th align="left">Left</th>
      <th align="center">Center</th>
      <th align="right">Right</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td align="left">L</td>
      <td align="center">C</td>
      <td align="right">R</td>
    </tr>
  </tbody>
</table>

Extended Syntax

Footnotes

Add footnotes for references:

Here's a sentence with a footnote.[^1]

[^1]: This is the footnote content.

Definition Lists

Some processors support definition lists:

Term
: Definition of the term

Another term
: Its definition

Abbreviations

The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

Emoji (GitHub)

:smile: :heart: :thumbsup:

Escaping Characters

Use backslashes to escape Markdown characters:

\*Not italic\*
\# Not a heading
\[Not a link\]

Characters that can be escaped: \ ` * _ { } [ ] ( ) # + - . !

HTML in Markdown

Most Markdown processors allow inline HTML:

This is regular Markdown.

<div class="custom">
  <p>This is HTML inside Markdown.</p>
</div>

Back to Markdown.

Common uses for HTML in Markdown:

  • Complex tables
  • Custom styling with classes
  • Details/summary elements
  • Embedding videos

Markdown Flavors

Different platforms extend Markdown with additional features:

GitHub Flavored Markdown (GFM)

  • Task lists
  • Tables
  • Autolinked URLs
  • Strikethrough
  • Emoji shortcodes
  • Syntax highlighting

CommonMark

A standardized specification aiming for consistency across implementations. Most modern Markdown parsers follow CommonMark as a baseline.

MultiMarkdown

Adds features like citations, footnotes, tables, and metadata headers.

Best Practices

Consistency

  • Choose one style for emphasis (* or _) and stick with it
  • Use consistent list markers (-, *, or +)
  • Add blank lines before and after headings

Readability

  • Use ATX-style headings (# Heading) rather than Setext style
  • Limit line length to 80-100 characters for raw readability
  • Use reference links for long or repeated URLs

Accessibility

  • Always include alt text for images
  • Use descriptive link text (avoid "click here")
  • Maintain proper heading hierarchy

Tools and Editors

Popular Markdown editors and tools:

  • VS Code: Built-in Markdown preview with extensions
  • Typora: WYSIWYG Markdown editor
  • Obsidian: Note-taking with Markdown
  • Notion: Supports Markdown input
  • StackEdit: Online Markdown editor

For quick conversions, use our Markdown to HTML Converter to instantly preview how your Markdown renders as HTML.

Markdown in Development

Static Site Generators

Many static site generators use Markdown for content:

  • Jekyll: Ruby-based, powers GitHub Pages
  • Hugo: Go-based, extremely fast
  • Gatsby: React-based with GraphQL
  • Next.js: Supports MDX (Markdown with JSX)

Documentation Platforms

  • GitBook: Documentation hosting
  • ReadTheDocs: Open source documentation
  • Docusaurus: Facebook's documentation framework

Converting Markdown

Command Line Tools

# Pandoc - universal document converter
pandoc input.md -o output.html
pandoc input.md -o output.pdf

# marked - Fast Markdown parser
npx marked -i input.md -o output.html

JavaScript Libraries

// marked
import { marked } from 'marked';
const html = marked.parse('# Hello World');

// markdown-it
import MarkdownIt from 'markdown-it';
const md = new MarkdownIt();
const html = md.render('# Hello World');

// remark (unified ecosystem)
import { remark } from 'remark';
import html from 'remark-html';
const result = await remark().use(html).process('# Hello');

Working with JSON and Markdown

When building APIs that serve Markdown content, you'll often need to handle JSON payloads. Use our JSON Formatter to validate and format your API responses.

For validating the structure of your content API responses, check out our JSON Schema Converter to generate validation schemas.

Conclusion

Markdown's simplicity and readability make it the ideal choice for technical documentation, blog posts, and content management. By mastering the syntax covered in this guide, you can write structured content that converts cleanly to HTML while remaining easily readable in its raw form.

Key takeaways:

  • Basic formatting uses intuitive symbols (*, #, -, etc.)
  • Extended syntax varies by implementation (GFM, CommonMark)
  • HTML can be used for features Markdown doesn't support
  • Consistent style improves readability
  • Many tools convert Markdown to various output formats

For more developer tools, explore our free online tools. For the complete Markdown specification, see the CommonMark Spec and GitHub's Markdown documentation.