36 lines
3.2 KiB
Plaintext
36 lines
3.2 KiB
Plaintext
---
|
||
title: Using HTML in Markdown
|
||
date: 2025-02-25T21:21:21-08:00
|
||
draft: 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](https://commonmark.org/) does not
|
||
cover, users are free to use HTML. However, the HTML tags that rendering
|
||
engines support vary considerably. For example, Hugo prefers
|
||
[shortcodes](https://gohugo.io/content-management/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. | [^HUGO] |
|
||
| `<kbd>` | Represent keyboard inputs or shortcuts. | — |
|
||
| `<abbr>` | Add tooltips to abbreviations for clarity. | [^NOHUGO] |
|
||
| `<sup>` and `<sub>` | Format text as superscript or subscript. | — |
|
||
| `<mark>` | Highlight text with a background color. | [^HUGO] |
|
||
| `<!-- ... -->` (HTML Comments) | Insert comments that won’t appear in the rendered output. | [^HUGO] |
|
||
| `<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. | [^GH] |
|
||
| `<samp>` | Denote sample output from programs or command-line operations, helping readers distinguish between code input and output. | [^GH] |
|
||
|
||
[^NOHUGO]: Not supported in Hugo.
|
||
|
||
[^HUGO]: Supported in Hugo, but may depend on the theme.
|
||
|
||
[^GH]: Not supported in GitHub
|