Markdown to HTML: Syntax Cheatsheet, Conversion Rules & Best Practices

Created in 2004 by John Gruber and Aaron Swartz, Markdown was designed with a simple, revolutionary goal: to allow writers and software developers to write using an easy-to-read, easy-to-write plain text format, and optionally convert it to structurally valid HTML.

Today, Markdown powers technical documentation across GitHub, README files, static site generators (Next.js, Astro, Hugo), CMS platforms, and communication hubs like Slack and Discord.

Understanding how Markdown elements map to semantic HTML tags helps you write accessible web content and clean blog posts.

---

Markdown to HTML Syntax Cheatsheet

Here is how common Markdown syntax compiles into semantic HTML markup:

| Markdown Syntax | Compiled HTML Output | Rendered Result | | :--- | :--- | :--- | | # Heading 1 | <h1>Heading 1</h1> | Main Page Heading | | ## Heading 2 | <h2>Heading 2</h2> | Section Heading | | **Bold text** | <strong>Bold text</strong> | Bold text | | *Italic text* | <em>Italic text</em> | Italic text | | ~~Strikethrough~~ | <del>Strikethrough</del> | ~~Strikethrough~~ | | [Anchor Text](https://url) | <a href="https://url">Anchor Text</a> | Anchor Text | | ![Alt text](image.png) | <img src="image.png" alt="Alt text" /> | Image element | | > Blockquote text | <blockquote>Blockquote text</blockquote> | Indented callout | | --- | <hr /> | Horizontal divider |

---

Code Blocks: Inline Code vs Syntax Highlighted Preformatted Text

Software documentation frequently includes snippets of computer code. Markdown provides two distinct mechanisms for code formatting:

1. Inline Code

Wrapping text in single backticks (`const x = 1`) compiles to an inline <code> tag:

<code>const x = 1</code>

This preserves monospace typography within paragraphs without breaking text flow.

2. Fenced Code Blocks

Wrapping multiple lines in triple backticks (```) compiles into a combined <pre><code> block:

```typescript
function greet(name: string): string {
  return `Hello, ${name}!`
}
```

Compiles into semantic markup ready for styling and Prism/Highlight.js syntax highlighters:

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

---

Lists: Ordered vs Unordered

Unordered Lists

Prefixing lines with hyphens (-) or asterisks (*) generates unordered <ul> list elements:

- React
- Next.js
- Tailwind CSS

Compiles to:

<ul>
  <li>React</li>
  <li>Next.js</li>
  <li>Tailwind CSS</li>
</ul>

Ordered Lists

Prefixing with numbers (1., 2., 3.) compiles to ordered <ol> containers:

<ol>
  <li>Clone repository</li>
  <li>Run npm install</li>
  <li>Start dev server</li>
</ol>

---

Semantic HTML Best Practices for Markdown Writers

To maintain high SEO visibility and accessibility when compiling Markdown into web pages:

1. Maintain Strict Heading Hierarchy: Never jump from an <h1> directly to an <h3>. Screen readers rely on orderly descending heading levels to navigate content.
2. Always Provide Image Alt Text: Use descriptive image descriptions inside the brackets ![Descriptive image alt text](path.png) for search engine image indexing and visually impaired users.
3. Use Relative Links for Internal Navigation: Internal links should point to relative routes (e.g., /tools/developer/markdown-to-html) to ensure correct routing across production and staging domains.

Try our free Markdown to HTML Converter for real-time split-screen editing, live HTML preview, and 1-click export.