Markdown HTML

Markdown is designed to be simple and easy to read, but it intentionally supports only a limited set of formatting features.

When you need more control over layout or formatting, you can insert raw HTML directly into your Markdown document.

Most modern Markdown parsers, including GitHub Flavored Markdown (GFM), CommonMark implementations, VS Code, Obsidian, GitLab, and many documentation frameworks, support a wide range of HTML elements.

Using HTML allows you to create layouts and formatting that are not possible with standard Markdown syntax alone.

Markdown covers most everyday formatting needs, including headings, lists, tables, images, links, and code blocks.

However, HTML becomes useful when you need features that Markdown doesn't provide.

Common use cases include:

• Centering text or images
• Creating collapsible sections
• Controlling image width and height
• Adding line breaks
• Using superscript and subscript
• Creating advanced tables
• Embedding videos or iframes (where supported)
• Building custom layouts

Whenever Markdown cannot achieve the desired formatting, HTML is often the best solution.

Yes.

Most Markdown editors allow raw HTML to be written directly inside Markdown files.

For example:

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

Output

Markdown automatically renders supported HTML elements while continuing to process normal Markdown syntax around them.

Markdown and HTML serve different purposes.

Feature	Markdown	HTML
Easy to write	✅	❌
Easy to read	✅	❌
Advanced formatting	Limited	Excellent
Styling options	Basic	Extensive
Learning curve	Easy	Moderate
Best for documentation	✅	✅

Markdown is ideal for fast writing and documentation, while HTML provides greater flexibility when advanced formatting is required.

Many documentation projects combine both to get the best of each.

Consider using HTML when you need:

• Custom image sizes
• Centered content
• Collapsible sections
• Responsive layouts
• Advanced tables
• Superscript or subscript
• Custom spacing
• Embedded multimedia

For everyday formatting such as headings, lists, links, blockquotes, and code blocks, standard Markdown syntax is usually the better choice because it is simpler and more portable.

Most modern Markdown editors support raw HTML.

Platform	HTML Support
GitHub	✅ Partial
GitLab	✅
VS Code Preview	✅
Obsidian	✅
Docusaurus	✅
MkDocs	✅
Hugo	✅
Astro Starlight	✅

Support may vary depending on the Markdown renderer and security settings. Some platforms restrict potentially unsafe HTML elements such as <script> or <iframe>.

Most Markdown editors support a wide range of HTML tags. The table below lists the most commonly used elements and their typical use cases.

HTML Tag	Supported	Common Use
<p>	✅	Paragraphs
<br>	✅	Line breaks
<hr>	✅	Horizontal rules
<img>	✅	Images
<a>	✅	Links
<strong>	✅	Bold text
<em>	✅	Italic text
<sup>	✅	Superscript
<sub>	✅	Subscript
<table>	✅	Advanced tables
<details>	✅ (GitHub)	Collapsible sections
<summary>	✅ (GitHub)	Accordion title
<kbd>	✅	Keyboard shortcuts
<mark>	Partial	Highlighted text
<div>	Partial	Layout container
<span>	Partial	Inline styling
<iframe>	❌ (Most platforms)	Embedded content
<script>	❌	Blocked for security

Most documentation only needs a small subset of these tags.

Markdown already creates paragraphs automatically, but you can also use HTML.

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

Output

HTML paragraphs are useful when combining Markdown with custom HTML layouts.

Markdown normally starts a new paragraph after a blank line.

For a simple line break, use the <br> tag.

First line.<br>
Second line.

Output

This is one of the most common HTML tags used in Markdown.

Markdown already supports horizontal rules using ---, but HTML provides an alternative.

<hr>

Output

In most cases, using Markdown syntax (---) is recommended because it is simpler and more portable.

Instead of Markdown syntax, you can use HTML formatting tags.

<strong>Bold Text</strong>

<em>Italic Text</em>

Output

For readability, Markdown syntax (**bold** and *italic*) is generally preferred unless you are already working with HTML.

Links can also be created using HTML.

<a href="https://example.com">Visit Website</a>

Output

Markdown links are shorter and easier to write, but HTML links provide additional attributes such as target, rel, and custom classes on supported platforms.

The HTML <img> tag gives you more control than standard Markdown image syntax.

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

Output

Unlike regular Markdown images, HTML images allow you to specify attributes such as:

• Width
• Height
• Loading
• Alignment (platform dependent)
• Alternative text

This makes HTML especially useful for documentation where image sizing is important.

Markdown tables work well for most documentation, but HTML tables support advanced layouts.

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

HTML tables allow merged cells, captions, and more complex structures that are not available in standard Markdown tables.

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

It allows you to create expandable and collapsible sections, helping keep long documentation clean and organized.

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

This content is hidden until the reader clicks the summary.

</details>

Output

This feature is commonly used for FAQs, installation instructions, troubleshooting steps, and lengthy examples.

Markdown does not include built-in syntax for superscript.

Use the HTML <sup> tag instead.

x<sup>2</sup>

Output

Common uses include:

• Mathematical formulas
• Footnote references
• Scientific notation

Use the <sub> tag for subscript text.

H<sub>2</sub>O

Output

Subscript is commonly used for:

• Chemical formulas
• Mathematical notation
• Scientific documentation

The <kbd> element highlights keyboard keys.

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

Output

This tag is especially useful in software documentation and tutorials.

Markdown does not support centered text or images.

HTML provides a simple solution.

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

Output

This approach is commonly used in GitHub README files for project titles, badges, and logos.

HTML also lets you center images.

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

Unlike standard Markdown images, HTML allows you to control both alignment and image size.

Many popular GitHub repositories use HTML to build professional-looking README files.

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

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

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

This combination of HTML and Markdown creates an attractive project homepage while remaining easy to maintain.

For security reasons, most Markdown renderers block certain HTML elements.

These commonly include:

• <script>
• <iframe>
• <embed>
• <object>
• <form>
• JavaScript event handlers (onclick, onload, etc.)

Blocking these tags helps prevent security vulnerabilities such as cross-site scripting (XSS).

Always check the documentation for your Markdown platform if you're unsure which HTML elements are allowed.

GitHub supports many useful HTML elements, including:

• <details>
• <summary>
• <img>
• <picture>
• <kbd>
• <sup>
• <sub>
• <br>
• <hr>
• <table>

However, GitHub removes potentially unsafe HTML, including scripts, embedded frames, and interactive form elements.

If you're writing documentation for GitHub, it's best to stick to supported tags and preview your README before publishing.

Using HTML inside Markdown can make your documentation more powerful, but it should be used carefully.

Follow these best practices to keep your documents clean, portable, and easy to maintain.

Use Markdown Whenever Possible

Markdown is easier to read and supported across virtually every Markdown editor.

For example, use Markdown instead of HTML for:

• Headings
• Lists
• Links
• Images
• Tables
• Code blocks
• Blockquotes

Reserve HTML for features that Markdown cannot provide.

Keep HTML Simple

Avoid writing complex HTML layouts inside Markdown documents.

Good example:

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

Avoid embedding large HTML structures unless absolutely necessary.

Test on Your Target Platform

Not every Markdown renderer supports the same HTML elements.

Always preview your document on the platform where it will be published.

Examples include:

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

This helps prevent unexpected rendering issues.

Avoid Inline CSS

Many Markdown platforms remove inline CSS for security reasons.

Instead of this:

<p style="color:red;">
Important
</p>

Use standard Markdown formatting or supported HTML elements whenever possible.

Add Alt Text to Images

Always include descriptive alternative text when using HTML images.

Good example:

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

Alt text improves accessibility and helps search engines understand image content.

Don't Mix Too Much HTML and Markdown

Combining small amounts of HTML with Markdown works well.

However, documents that contain mostly HTML become harder to read and maintain.

Aim to keep Markdown as the primary syntax.

Here are the most common mistakes beginners make.

Forgetting to Close HTML Tags

Incorrect:

<p>This paragraph never closes.

Correct:

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

Always close HTML elements properly unless they are self-closing tags.

Using Unsupported HTML

Not every HTML element works in Markdown.

For example:

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

Most Markdown renderers remove JavaScript entirely for security reasons.

Relying on CSS Styling

Markdown is intended for content, not advanced page design.

Heavy CSS customization often won't work on platforms like GitHub.

Expecting HTML to Work Everywhere

Some documentation tools allow nearly all HTML.

Others remove or sanitize unsupported tags.

Always check your platform's documentation before depending on specific HTML features.

HTML in Markdown appears in many types of technical documentation.

Project Logo

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

Expandable FAQ

<details>
<summary>How do I install the project?</summary>

Run:

```bash
npm install
```

</details>

Keyboard Shortcut

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

Chemical Formula

CO<sub>2</sub>

Mathematical Expression

x<sup>3</sup>

These examples are commonly found in GitHub repositories, software documentation, programming tutorials, and technical blogs because they provide formatting that standard Markdown alone cannot achieve.

The easiest way to learn HTML in Markdown is by experimenting with real examples.

Open the Markdown Editor to test HTML tags alongside Markdown syntax. Preview the rendered output instantly, then export your document as HTML, PDF, DOCX, or other supported formats using the Markdown to HTML and HTML to Markdown conversion tools.

Markdown provides a clean and simple syntax for writing documentation, while HTML adds flexibility when advanced formatting is required.

In this guide, you learned:

• What HTML in Markdown is
• When to use HTML instead of Markdown
• Supported HTML tags
• HTML images, tables, links, and line breaks
• Collapsible sections using <details> and <summary>
• GitHub HTML support
• Best practices
• Common mistakes
• Frequently asked questions

Combining Markdown with carefully chosen HTML elements allows you to create professional documentation that remains easy to read, portable, and maintainable across GitHub, VS Code, Obsidian, GitLab, and other Markdown platforms.

Continue learning Markdown with these guides:

Available now

• Markdown Basics — core concepts for beginners
• Markdown Cheat Sheet — quick syntax lookup
• Markdown Syntax — complete reference with examples
• Markdown Headings — document structure with H1–H6
• Markdown Paragraphs — blank lines and spacing
• Markdown Lists — ordered, unordered, nested, and task lists
• Markdown Links — inline, reference, and relative links
• Markdown Images — syntax, URLs, alt text, and GitHub paths
• Markdown Tables — syntax, alignment, and GitHub GFM
• Markdown Code Blocks — fenced blocks and syntax highlighting
• Markdown Blockquotes — syntax, nesting, and GitHub callouts
• Markdown Horizontal Rules — section dividers with ---, ***, and ___
• Markdown HTML — use HTML tags inside Markdown documents
• Markdown Task Lists — checkbox syntax, nested checklists, and GitHub GFM
• Markdown Footnotes — references, citations, and GitHub GFM support
• GitHub Markdown — GFM syntax, README examples, and GitHub-specific features

The best way to learn HTML in Markdown is by writing it yourself. Open the Markdown Editor to experiment with HTML tags, collapsible sections, and image sizing while previewing the rendered output in real time.