| Code blocks in tables |
Markdown code blocks (```) inside table cells often break layout or collapse formatting. |
Markdown parsers vary in how they handle nested code blocks. Some strip indentation or misalign rows. |
Use <table><td><pre>...</pre></td></table> for full control. |
| Mixed syntax nesting |
Combining lists, tables, and code blocks leads to unpredictable rendering. |
Markdown lacks a formal grammar for deeply nested structures. |
HTML allows explicit nesting with <ul>, <table>, <pre>, etc.` |
| Whitespace collapse |
YAML or shell blocks lose indentation fidelity. |
Markdown collapses multiple spaces unless inside code fences. |
<pre> preserves exact spacing and indentation. |
| Escaping special characters |
Characters like <, &, > may be interpreted as HTML. |
Markdown auto-converts these unless escaped manually. |
HTML lets you use <, &, > explicitly. |
| Syntax highlighting inconsistency |
Language hints (```yaml) may not trigger consistent highlighting across renderers. |
Depends on the markdown engine (e.g., GitHub vs GitLab vs VS Code). |
HTML can embed <code class="language-yaml"> with CSS/JS support. |
| Link ambiguity |
[text](url) may be misrendered inside nested blocks or tables. |
Markdown link parsing is context-sensitive and brittle. |
HTML <a href="...">text</a> is explicit and reliable. |
| Image rendering |
 may break inside tables or lists. |
Markdown image syntax is fragile in nested contexts. |
HTML <img src="..." alt="..."> is stable and stylable. |
| Inline HTML in Markdown |
Mixing HTML and Markdown leads to unpredictable results. |
Markdown engines differ in how they parse inline HTML. |
Use pure HTML for structural consistency. |
| Footnotes and annotations |
Markdown footnotes ([^1]) are not universally supported. |
Not part of core spec; requires extensions. |
HTML <sup> and <aside> offer semantic alternatives. |