Add HTML in Markdown notes

2025-02-26 18:14:41 -08:00
parent 5a6e2cfdaa
commit 3f099eb33c
1 changed files with 39 additions and 0 deletions
@@ -0,0 +1,39 @@
+---
+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.                                                                                  | [^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.
+