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.

For example, HTML is commonly used to:

• Resize images
• Center text or images
• Create collapsible sections
• Add superscript and subscript
• Display keyboard shortcuts
• Build advanced table layouts

Use Markdown whenever it provides the formatting you need. Switch to HTML only when Markdown cannot achieve the desired result.

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 Markdown and HTML to keep documents readable while still supporting advanced layouts where needed.

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 provides greater control over structure and presentation.

For most documentation, start with Markdown and introduce HTML only where additional control is required.

Need a complete comparison? Read the Markdown vs HTML guide for syntax differences, portability, and common workflows.

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.

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.

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
• Optional documentation

Parser Tip#

If you're placing Markdown content—such as lists, code blocks, or blockquotes—inside a <details> element, leave a blank line after the <summary> tag.

Some Markdown parsers won't process nested Markdown correctly without that spacing.

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.

Mixing Markdown Inside HTML Incorrectly#

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

Without proper spacing, Markdown syntax may be displayed as plain text instead of being rendered.

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#

<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>

Expandable FAQ#

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

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

</details>

Keyboard Shortcut#

Press <kbd>Ctrl</kbd> + <kbd>C</kbd> to copy.

Scientific Formula#

CO<sub>2</sub>

Mathematical Expression#

x<sup>3</sup>

These patterns are commonly used in GitHub repositories, technical documentation, product manuals, and developer guides because they solve formatting problems that standard Markdown cannot.