Andrew StrykerandClaude Opus 4.6
403da45ff1
Brings in renv, archetypes, layout partials, shortcodes, gitignore, and hugo config changes that were committed on the post branch. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
43 lines
3.3 KiB
Markdown
43 lines
3.3 KiB
Markdown
---
|
||
title: Using HTML in Markdown
|
||
date: 2025-02-25T21:21:21-08:00
|
||
draft: false
|
||
tags:
|
||
- Writing
|
||
- Markdown
|
||
- HTML
|
||
- Hugo
|
||
---
|
||
|
||
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. 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.
|
||
|
||
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. | — |
|
||
| `<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] |
|
||
|
||
[^NOHUGO]: Not supported in Hugo.
|
||
|
||
[^HUGO]: Supported in Hugo, but may depend on the theme.
|
||
|
||
[^GH]: Not supported in GitHub
|