website/content/notes/html-in-markdown-recommendation.md

title, date, draft

title	date	draft
Using HTML in Markdown	2025-02-25T21:21:21-08:00	false

Markdown uses punctuation-based syntax to format text, drawing inspiration from plain text email conventions. The goal is for Markdown documents to be easy to read. For concerns that the specification does not cover, users are free to use HTML. However, the HTML tags that rendering engines support vary considerably. For example, Hugo prefers shortcodes extensions to raw HTML tags. Generally, best practice is to avoid mixing Markdown and HTML, as doing so can detract from Markdown’s intended simplicity and readability.

The following items are exceptions to this rule—cases where HTML provides functionality or control that Markdown does not.

HTML Tag(s)	Description	Notes
<details> and <summary>	Create collapsible sections for hiding and revealing content.	1
<kbd>	Represent keyboard inputs or shortcuts.	—
<abbr>	Add tooltips to abbreviations for clarity.	—
<sup> and <sub>	Format text as superscript or subscript.	—
<mark>	Highlight text with a background color.	2
<!-- ... --> (HTML Comments)	Insert comments that won’t appear in the rendered output.	3
<img>	Embed images with enhanced control over attributes like class, style, width, and height.	—
<var>	Represent variables, parameters, or mathematical symbols to add semantic clarity in technical documentation.	—
<samp>	Denote sample output from programs or command-line operations, helping readers distinguish between code input and output.	—

---

1. While GitHub supports <details> and <summary> in GitHub Flavored Markdown, Hugo’s support may vary based on configuration and theme. ↩︎

2. The <mark> tag is supported on GitHub; however, styling might differ in Hugo depending on theme defaults. ↩︎

3. HTML comments (<!-- ... -->) are preserved in GitHub’s rendered output but may be stripped or altered in some Hugo configurations. ↩︎