HTML in Markdown

Markdown covers the common structure well. An occasional HTML fragment can fill a real gap—when the output is known and a readable Markdown fallback still carries the meaning.

MarkIOY Team · August 11, 2026 · 9 min read

When HTML helps

Many Markdown parsers pass a subset of HTML through to the rendered page. This provides an escape hatch for structures that core Markdown does not express well: a collapsible detail block, an image with dimensions, a keyboard shortcut, or a short embedded media frame.

It is not a way to turn a Markdown document into an unrestricted web page. The same file may be rendered by a static-site generator, a repository viewer, a note app, an email client, or a knowledge base. Each can allow, escape, strip, or sanitize HTML differently.

Useful HTML snippets

Collapsible detail

Use this for an optional explanation that would otherwise interrupt the main reading flow. Put the important conclusion before the disclosure; some readers will not see or open it.

<details>
<summary>Why is this optional?</summary>

This explanation is available when a reader needs it.
</details>

An image with size and useful alternative text

Markdown images are usually the most portable choice. HTML becomes useful when a renderer honors image dimensions and the layout needs a predictable maximum width.

<img src="/editor-visual.png"
     alt="A document open in source and preview views"
     width="720">

Do not rely on style attributes for essential layout. They are commonly removed, and a fixed pixel size can be poor on a narrow screen.

Keyboard input and a highlighted term

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

<mark>Review this assumption before publishing.</mark>

These inline elements enrich meaning without requiring scripts or custom styling. If a renderer strips the tags, the words still remain.

A controlled media embed

An iframe can embed a video, map, or interactive prototype only when the target renderer permits it and the remote site permits framing. Always include a normal link immediately before or after the embed.

<p><a href="https://markioy.com/">Open MarkIOY directly</a></p>
<iframe src="https://markioy.com/" title="MarkIOY home" loading="lazy"></iframe>

Why HTML sometimes does not render

Sanitization is a security feature. Scripts, event handlers such as onclick, embedded styles, forms, and frames can create cross-site scripting, tracking, or phishing risks. A platform may remove them without warning, even though the same fragment works in a local browser preview.

<button onclick="this.textContent = 'Ran in the sandbox'">Run local HTML</button>
<script>document.body.dataset.demo = 'active'</script>

Safe, durable practice

Start with portable Markdown

Headings, lists, links, images, tables, code fences, and Mermaid source cover most documentation needs. If the document loses its meaning when one HTML tag is removed, the content is too dependent on a renderer-specific feature.

Build a graceful fallback beside the fragment

Put the key statement outside details, provide a link for every embedded frame, and describe every image. Treat enhanced HTML as progressive enhancement: it can improve the preferred view but must not be the only route to information or an action.

Use trusted, stable sources

For images and frames, use HTTPS URLs you control or trust. Do not embed credentials, private query parameters, or third-party widgets without considering privacy and data collection. A document can be copied much farther than its original context.

Test the final pipeline

Check the source, the editor preview, the published page, and any export format that matters. Also test a narrow viewport and keyboard navigation. The renderer that matters is the one your reader actually uses.