<details>
<summary>Click to reveal</summary>
Hidden content
</details>One of the defining design decisions John Gruber made when creating Markdown was establishing that Markdown is not a replacement for HTML—it is a shorthand writing format that coexists with HTML.
Whenever Markdown lacks a native syntax for a particular layout requirement—such as audio playback, custom collapsible accordions, fine-grained text alignment, or keyboard keycaps—you can drop standard HTML tags directly into your .md file.
In CommonMark and Oyma, safe HTML elements pass through cleanly, giving you immense layout power while retaining plain-text portability.
Safe HTML tags commonly used in Markdown
The following HTML tags are widely used to extend Markdown capabilities:
1. Interactive disclosures: <details> and <summary>
Create clean collapsible dropdowns without external plugins or JavaScript:
<details>
<summary>Click to view system audit logs</summary>
<p>All network traffic was confined to localhost (127.0.0.1).</p>
<p>Zero external outbound packets recorded during test run.</p>
</details>When rendered, the browser provides a native disclosure triangle that expands and collapses on click.
2. Audio players: <audio>
Embed playable local audio recordings directly into meeting notes:
<audio controls src="attachments/meeting-audio.m4a">
Your browser does not support audio playback.
</audio>3. Native keycaps: <kbd>
Style keyboard shortcut combinations:
Press <kbd>⌘</kbd> + <kbd>O</kbd> to launch the command palette.4. Semantic text formatting: <sub>, <sup>, and <mark>
Apply subscripts, superscripts, and highlighted text:
H<sub>2</sub>O and E = mc<sup>2</sup>
This phrase is <mark>highlighted with HTML</mark>.5. Centered text and line breaks: <center> and <br>
<br>
Line break within a table cell or poetic verse.Parsing Markdown inside HTML blocks
A critical rule of the CommonMark specification concerns how Markdown is parsed inside raw HTML blocks:
<!-- Markdown inside standard HTML blocks is NOT parsed -->
<div>
**This text will NOT be bold** because it is inside a raw HTML block.
</div>
<!-- Solution: Use blank lines to allow CommonMark parsing -->
<div>
**This text WILL be bold** because blank lines re-enter Markdown mode.
</div>To parse Markdown syntax inside HTML tags, always separate the inner Markdown content from the bounding HTML tags with empty blank lines.
Security sanitization rules in Oyma
When rendering HTML inside Markdown files, security and privacy are paramount. Unlike web browsers that execute arbitrary third-party scripts, Oyma enforces strict local-first security policies:
- Allowed safe tags:
<details>,<summary>,<kbd>,<sub>,<sup>,<mark>,<audio>,<span>,<div>,<br>,<hr>. - Blocked unsafe elements:
<script>tags, third-party tracking beacons, eager cross-origin<iframe>tags, and unvetted web embeds are neutralized. - Local asset isolation: Media files (
<audio>,<img>) only load from local vault directories or verified click-to-load origins.
HTML in Oyma on macOS
In Oyma:
- HTML tags like
<details>and<kbd>render as native macOS components matching Apple system typography and dark mode. - Raw HTML remains completely readable and editable in your plain-text files.
- Exporting to PDF, DOCX, or HTML preserves your custom structures faithfully.
Frequently asked questions
- Can I use raw HTML tags inside a Markdown file?
- Yes. CommonMark and GitHub Flavored Markdown explicitly permit raw HTML tags. Any HTML element not covered by Markdown syntax (such as ``, ``, `