2025-02-26 18:14:41 -08:00
|
|
|
|
---
|
|
|
|
|
|
title: Using HTML in Markdown
|
|
|
|
|
|
date: 2025-02-25T21:21:21-08:00
|
|
|
|
|
|
draft: false
|
2025-02-26 20:03:13 -08:00
|
|
|
|
tags:
|
|
|
|
|
|
- Writing
|
|
|
|
|
|
- Markdown
|
|
|
|
|
|
- HTML
|
|
|
|
|
|
- Hugo
|
2025-02-26 18:14:41 -08:00
|
|
|
|
---
|
|
|
|
|
|
|
|
|
|
|
|
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
|
2025-02-26 20:15:53 -08:00
|
|
|
|
engines support vary considerably. Further, some rendering engines have their
|
|
|
|
|
|
own approach to extensions, like
|
|
|
|
|
|
[shortcodes](https://gohugo.io/content-management/shortcodes/) in Hugo.
|
|
|
|
|
|
Generally, best practice is to avoid mixing Markdown and HTML, as doing so can
|
|
|
|
|
|
detract from Markdown’s intended simplicity and readability.
|
2025-02-26 18:14:41 -08:00
|
|
|
|
|
|
|
|
|
|
The following items are exceptions to this rule—cases where HTML provides
|
|
|
|
|
|
functionality or control that Markdown does not.
|
|
|
|
|
|
|
2025-04-08 08:26:41 -07:00
|
|
|
|
| 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. | — |
|
|
|
|
|
|
| `<div>` | Apply specific styles elements, such as centering an image, to a section of text | |
|
|
|
|
|
|
| `<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] |
|
2025-02-26 18:14:41 -08:00
|
|
|
|
|
2025-02-26 19:29:50 -08:00
|
|
|
|
[^NOHUGO]: Not supported in Hugo.
|
|
|
|
|
|
|
2025-02-26 19:23:43 -08:00
|
|
|
|
[^HUGO]: Supported in Hugo, but may depend on the theme.
|
2025-02-26 18:14:41 -08:00
|
|
|
|
|
2025-02-26 19:23:43 -08:00
|
|
|
|
[^GH]: Not supported in GitHub
|
