HTML in Markdown

Markdown is intentionally simple, which makes it easy to write and read. When you need formatting beyond the core Markdown syntax, you can embed supported HTML directly in your document.

Most modern Markdown parsers—including GitHub Flavored Markdown (GFM), CommonMark-based editors, VS Code, Obsidian, GitLab, and many documentation frameworks—support a wide range of HTML elements alongside standard Markdown. The When Should You Use HTML? section below lists the specific cases where it's worth reaching for.

Markdown is the better choice for common formatting such as headings, lists, links, images, tables, blockquotes, and code blocks because it is shorter, easier to read, and works consistently across most platforms.

HTML becomes useful when you need features like:

• Custom image dimensions
• Centered content
• Collapsible sections using <details>
• Advanced tables with merged cells
• Superscript and subscript
• Keyboard shortcut formatting
• Additional HTML attributes supported by your Markdown renderer

Many documentation projects combine both — Markdown for readability, HTML for the specific layouts it can't achieve alone.

Yes. Most modern Markdown editors and documentation platforms allow raw HTML inside Markdown documents.

Example

<p>This paragraph is written using HTML.</p>

In supported Markdown parsers, HTML is rendered normally while the surrounding Markdown continues to work as expected.

💡 Note: HTML support depends on the Markdown renderer. Some platforms allow most HTML elements, while others sanitize or remove unsupported tags for security reasons.

Markdown and HTML solve different problems — Markdown focuses on readability and speed, while HTML gives you more control over structure and presentation. This section focuses on the specific capabilities HTML adds; for the full format-level comparison (syntax, learning curve, browser support, when to choose each), see the Markdown vs HTML guide.

For most documentation, start with Markdown and introduce HTML only where one of these specific capabilities is needed.

Raw HTML is supported by most modern Markdown editors, but every renderer applies its own parsing and security rules.

Always preview your document on the platform where it will be published, since supported HTML can vary between renderers.

The following HTML elements are the ones most commonly used in Markdown documents.

Most documentation only needs a small subset of these tags. Keeping HTML minimal makes documents easier to maintain and improves portability across Markdown editors.

Markdown and HTML can usually be combined in the same document.

Example

# Installation

<p align="center">
<img src="logo.png" alt="Project Logo" width="180">
</p>

Run:

```bash
npm install
```

This approach is common in GitHub README files, documentation sites, and technical guides because it combines Markdown's readability with HTML's additional formatting capabilities.

Use Markdown for content first, then add HTML only where Markdown cannot achieve the required layout.

When you place Markdown content inside block-level HTML elements such as <details> or <div>, some Markdown parsers require a blank line before the Markdown content begins.

Example

<details>
<summary>Show installation steps</summary>

```bash
npm install
npm run dev
```

</details>

Without the blank line, some Markdown renderers may treat the content as plain text instead of parsing the Markdown syntax correctly.

Parser behavior varies between implementations, so always preview complex HTML and Markdown combinations in your target platform. This is the one rule in this guide worth double-checking every time — it's the most common cause of "my code block inside a collapsible section isn't rendering."

Standard Markdown image syntax is enough for most documentation:

![Project Logo](logo.png)

Use the HTML <img> tag when you need additional control over the image.

<img src="logo.png" alt="Project Logo" width="300">

Common attributes include:

• width
• height
• alt
• loading (where supported)
• decoding (renderer dependent)

This is especially useful for project logos, screenshots, diagrams, and documentation where consistent image sizing improves readability.

Need standard Markdown image syntax? See the Markdown Images guide. For a full walkthrough of resizing, centering, and captioning images specifically — with more examples than this reference covers — see How to Add Images in Markdown.

Markdown doesn't include built-in syntax for centering text or images.

For GitHub README files and many Markdown renderers, HTML provides the most compatible solution.

<p align="center">
Welcome to MDConvertHub
</p>

To center an image:

<p align="center">
  <img src="logo.png" alt="Project Logo" width="180">
</p>

💡 Compatibility note: The align="center" attribute is deprecated in modern HTML5. However, GitHub Flavored Markdown (GFM) still supports it and it remains the most widely used approach for centering README content.

Markdown links are shorter:

[Visit Website](https://example.com)

Use HTML when additional attributes are required.

<a href="https://example.com"
   target="_blank"
   rel="noopener noreferrer">
   Visit Website
</a>

HTML links are useful when your Markdown platform supports attributes such as:

• target
• rel
• download
• title

Support varies by renderer, and some platforms remove unsupported attributes during sanitization.

Markdown tables work well for most documentation.

Use HTML tables only when you need features Markdown doesn't support.

<table>
  <tr>
    <th>Name</th>
    <th>Role</th>
  </tr>
  <tr>
    <td>John</td>
    <td>Developer</td>
  </tr>
</table>

HTML tables support capabilities such as:

• merged cells (rowspan, colspan)
• captions
• nested content
• more complex layouts

If a simple table is enough, Markdown remains easier to read and maintain.

Looking for normal table syntax? See the Markdown Tables guide.

One of the most useful HTML features supported by GitHub Markdown is the <details> element.

<details>
<summary>Click to expand</summary>

This content is hidden until the reader opens the section.

</details>

Collapsible sections are commonly used for FAQs, installation steps, troubleshooting, long examples, and optional documentation.

If you're nesting lists, code blocks, or blockquotes inside, remember the blank-line rule from Markdown Inside HTML Blocks above — leave a blank line after the <summary> tag so parsers process the nested Markdown.

Several HTML elements are especially useful in developer documentation.

Superscript#

x<sup>2</sup>

Common uses:

• Mathematical notation
• Footnotes
• Scientific documentation

Subscript#

H<sub>2</sub>O

Common uses:

• Chemical formulas
• Scientific writing
• Mathematical expressions

Keyboard Shortcuts#

Press <kbd>Ctrl</kbd> + <kbd>S</kbd> to save.

The <kbd> element is widely used in documentation, tutorials, and software manuals because it clearly distinguishes keyboard input from regular text.

For security reasons, many Markdown platforms sanitize raw HTML before rendering it.

The following elements are commonly blocked or removed:

• <script>
• <iframe>
• <embed>
• <object>
• <form>
• JavaScript event handlers such as onclick, onload, and onerror

These restrictions help prevent cross-site scripting (XSS) and other security issues.

If embedded content doesn't render, check your platform's documentation instead of assuming the HTML is incorrect.

Prefer Markdown First#

Markdown is shorter, easier to maintain, and works consistently across nearly every Markdown editor.

Use HTML only when Markdown cannot provide the layout or functionality you need.

Keep HTML Simple#

Small HTML snippets are easy to understand.

Good example

<img src="logo.png" alt="Project Logo" width="250">

Avoid turning an entire Markdown document into an HTML page unless there's a specific requirement.

Test on Your Target Platform#

HTML support isn't identical everywhere.

Always preview documents before publishing to platforms such as:

• GitHub
• GitLab
• VS Code
• Obsidian
• Docusaurus
• MkDocs

The same document can render differently depending on the Markdown parser.

Always Add Alt Text#

When using the <img> tag, include descriptive alternative text.

<img src="diagram.png"
     alt="Markdown rendering workflow"
     width="500">

Alt text improves accessibility and provides useful context if an image fails to load.

Avoid Depending on CSS#

Many Markdown renderers remove inline styles or ignore external CSS.

Instead of relying on styling, use supported HTML elements and keep layouts simple for better portability.

Keep Markdown Readable#

Mixing a few HTML elements with Markdown works well.

Large HTML layouts quickly become difficult to edit and reduce one of Markdown's biggest advantages—its readability.

Forgetting to Close HTML Tags#

Incorrect

<p>This paragraph never closes.

Correct

<p>This paragraph closes correctly.</p>

Always close HTML elements unless they're self-closing tags.

Assuming Every HTML Tag Works#

Not every Markdown renderer supports the same HTML elements.

For example:

<script>
alert("Hello");
</script>

Most documentation platforms remove JavaScript completely for security reasons.

Missing the Blank-Line Rule Inside HTML Blocks#

See Important: Markdown Inside HTML Blocks earlier on this page — this is the most common cause of nested Markdown rendering as plain text instead of formatted content.

Using HTML When Markdown Is Simpler#

Many beginners replace standard Markdown with HTML unnecessarily.

Instead of:

<strong>Bold</strong>

Prefer:

**Bold**

The Markdown version is shorter, easier to read, and more portable.

Depending on Platform-Specific Behavior#

Some HTML features work perfectly on GitHub but behave differently in other Markdown editors.

If you're publishing documentation for multiple platforms, test your document before releasing it.

GitHub README Header — combining several of the patterns above into one realistic block:

<p align="center">
  <img src="logo.png" alt="Project Logo" width="160">
</p>

<h1 align="center">MDConvertHub</h1>

<p align="center">
Markdown Tools & Documentation
</p>

This pattern is common across GitHub repositories, technical documentation, and product manuals because it solves a formatting problem — a centered header block — that standard Markdown can't achieve alone.