# Render Gotchas

Course: [Markdown](https://www.devtutorials.ai/learn/markdown) · Section: Reference
Source: https://www.devtutorials.ai/learn/markdown/reference/render-gotchas

> Look up what you see, find the cause and the fix: headings, lists, links, code, tables, escaping, frontmatter errors and agent-file problems, each linked to its lesson.

## Render Gotchas

Look up what you see, find the cause, apply the fix. Each section links to the lesson that explains it. The boxes show the most common problems broken first and fixed second, so you can compare them.

## The Ten Most Common

````md runnable title="Ten gotchas, broken then fixed"
#Not a heading
# A heading

Line one
Line two, joined to line one

Line one\
Line two, on its own line

- Install
 - Node 20 (not nested)
- Install
  - Node 20 (nested)

[broken link] (docs/refunds.md)
[working link](docs/refunds.md)

Call refund*order*total
Call `refund*order*total`

The API returns List<string>
The API returns `List<string>`

Fixed refund rounding.
---

![](refund-flow.svg)
![Refund flow: request, check, approve](/markdown-assets/refund-flow.svg)
````

Open the Rendered tab and read it from the top. Each broken line is followed by its fix. The `---` under "Fixed refund rounding." turned it into a heading: leave a blank line above a divider.

## Explore the Edge Cases

The explorer below holds over 70 tricky snippets. Pick one to see how CommonMark, GitHub (GFM) and a docs site each render it. Snippets marked as different are the ones that change between renderers.

## Headings and Paragraphs

| What you see | Cause | Fix | Lesson |
|---|---|---|---|
| `#Title` shows with the `#` | no space after `#` | `# Title` | [Headings](/learn/markdown/fundamentals/headings-and-paragraphs) |
| Lines run together into one paragraph | a single line break does not start a new line | blank line between paragraphs | [Headings](/learn/markdown/fundamentals/headings-and-paragraphs) |
| An address prints on one line | no hard line break | end each line with `\` | [Headings](/learn/markdown/fundamentals/headings-and-paragraphs) |
| A line break vanished after saving | the editor removed two trailing spaces | use `\` instead | [Headings](/learn/markdown/fundamentals/headings-and-paragraphs) |
| A sentence became a big heading | `---` right under it | blank line above `---` | [Headings](/learn/markdown/fundamentals/headings-and-paragraphs) |
| A section is missing from the page menu | it is a bold line, not a heading | use `##` | [Headings](/learn/markdown/fundamentals/headings-and-paragraphs) |
| `** text **` shows the stars | spaces just inside the stars | `**text**` | [Headings](/learn/markdown/fundamentals/headings-and-paragraphs) |
| A heading link stopped working | the heading was renamed | update the `#anchor` links | [Links](/learn/markdown/fundamentals/links-and-images) |

## Lists

| What you see | Cause | Fix | Lesson |
|---|---|---|---|
| Inner items are not nested | not indented to the text above | 2 spaces under `- `, 3 under `1. ` | [Lists](/learn/markdown/fundamentals/lists-and-nesting) |
| One list shows as several | the bullet mark changed | one mark everywhere | [Lists](/learn/markdown/fundamentals/lists-and-nesting) |
| Numbering restarts, or "1" twice | an unindented paragraph ended the list | indent it under the step | [Lists](/learn/markdown/fundamentals/lists-and-nesting) |
| A code block breaks the list | the fence is not indented | indent it to the step's text | [Lists](/learn/markdown/fundamentals/lists-and-nesting) |
| A sentence starting with a year became a list | `2023.` looks like a list number | `2023\.` | [Lists](/learn/markdown/fundamentals/lists-and-nesting) |
| `[ ]` shows as text | task lists are GFM-only | a GFM renderer, or words | [Lists](/learn/markdown/fundamentals/lists-and-nesting) |

## Links and Images

| What you see | Cause | Fix | Lesson |
|---|---|---|---|
| `[text] (path)` as plain text | a space between `]` and `(` | remove it | [Links](/learn/markdown/fundamentals/links-and-images) |
| The whole link shows as text | a space inside the path | no spaces in names; or `< >` or `%20` | [Links](/learn/markdown/fundamentals/links-and-images) |
| `[text][label]` shows as text | the label has no matching definition | match label and definition | [Links](/learn/markdown/fundamentals/links-and-images) |
| An address is not clickable | bare addresses link only in GFM | wrap it in `< >` | [Flavors](/learn/markdown/team-docs/markdown-flavors) |
| A screen reader says nothing for an image | empty alt text | describe the picture | [Links](/learn/markdown/fundamentals/links-and-images) |
| An image is huge | Markdown has no size | an HTML `img` with `width` | [Links](/learn/markdown/fundamentals/links-and-images) |

## Code

| What you see | Cause | Fix | Lesson |
|---|---|---|---|
| The rest of the page is one grey code box | a code block was never closed | add the closing fence | [Code](/learn/markdown/fundamentals/code-blocks) |
| A paragraph shows as code | it starts with four spaces | remove the leading spaces | [Code](/learn/markdown/fundamentals/code-blocks) |
| An example fence closes the outer block | both use three backticks | four backticks outside | [Code](/learn/markdown/fundamentals/code-blocks) |
| No colours in the code | no language hint | ` ```bash `, ` ```json ` … | [Code](/learn/markdown/fundamentals/code-blocks) |
| A copied command fails with `$: command not found` | the `$` prompt was copied | remove the prompt | [Code](/learn/markdown/fundamentals/code-blocks) |

## Tables

| What you see | Cause | Fix | Lesson |
|---|---|---|---|
| A paragraph full of pipes | no divider row, or no GFM | add `\|---\|`; or use a list | [Tables](/learn/markdown/fundamentals/tables-and-quotes) |
| A cell's text vanished | more cells than the header | match the header | [Tables](/learn/markdown/fundamentals/tables-and-quotes) |
| A cell split in two | a `\|` inside it | write `\\|` | [Tables](/learn/markdown/fundamentals/tables-and-quotes) |
| A row ends early | a line break inside a cell | one line per row; `<br>` if needed | [Tables](/learn/markdown/fundamentals/tables-and-quotes) |
| `[!WARNING]` shows as text | alerts are a platform extension | `> **Warning:**` as a fallback | [Flavors](/learn/markdown/team-docs/markdown-flavors) |

## Escaping and HTML

| What you see | Cause | Fix | Lesson |
|---|---|---|---|
| Part of a formula went italic | stars touching words | backticks, or `\*` | [Escaping](/learn/markdown/fundamentals/escaping-and-html) |
| A type name or placeholder vanished | text in angle brackets is read as HTML | backticks | [Escaping](/learn/markdown/fundamentals/escaping-and-html) |
| A sentence became a list or quote | it starts with `+`, `-`, `>` or `1.` | escape the first character | [Escaping](/learn/markdown/fundamentals/escaping-and-html) |
| Markdown inside `<details>` is raw text | no blank line after the HTML tag | blank lines around the Markdown | [Escaping](/learn/markdown/fundamentals/escaping-and-html) |
| An agent obeys an invisible rule | the rule is in an HTML comment | delete it, or write it as a line | [Escaping](/learn/markdown/fundamentals/escaping-and-html) |
| A docs page fails to build | MDX reads `{` or `<` as code | backticks | [Flavors](/learn/markdown/team-docs/markdown-flavors) |

## Frontmatter Error Messages

These are the messages YAML parsers print, with what they usually mean.

| Message | Usual cause | Fix |
|---|---|---|
| `Nested mappings are not allowed in compact mappings` | a value contains `: ` | put the value in quotes |
| `Tabs are not allowed as indentation` | a tab in the indent | use spaces |
| `Unresolved alias` | a value starts with `*` or `&` | put it in quotes |
| `Plain value cannot start with reserved character @` | a value starts with `@` | put it in quotes |
| `Map keys must be unique` | a key appears twice | delete one |
| No error, but a title is cut off | ` #` started a comment | put it in quotes |
| No error, but `1.10` became `1.1` | it was read as a number | put it in quotes |
| A divider and a heading at the top of the page | the renderer does not read frontmatter, or it is not on line 1 | move it to line 1; use a tool that reads it |

```md runnable frontmatter expect-error title="A frontmatter error to read" dialect="docs"
---
title: Refunds: the rules
owner: support-team
---

# Refunds
```

Open the Outline tab to see the message and its line number. Then quote the title.

## Agent Files

| What you see | Cause | Fix | Lesson |
|---|---|---|---|
| The agent follows some rules and misses others | `AGENTS.md` is long and vague | keep only what the code cannot say | [AGENTS.md](/learn/markdown/ai-native/agents-md) |
| The agent runs the wrong test command | no exact commands | a `## Commands` section | [AGENTS.md](/learn/markdown/ai-native/agents-md) |
| Claude Code ignores `AGENTS.md` | a `CLAUDE.md` exists without the import | `@AGENTS.md` in `CLAUDE.md` | [AGENTS.md](/learn/markdown/ai-native/agents-md) |
| A skill is never used | vague description, or no "when" | what it does, when, and when not | [Skills](/learn/markdown/ai-native/skills-and-subagents) |
| A skill is used for the wrong tasks | description too broad | specific words and "Do not use for …" | [Skills](/learn/markdown/ai-native/skills-and-subagents) |
| A skill or subagent does not appear at all | broken frontmatter, or a missing field | quote values; add `name` and `description` | [Skills](/learn/markdown/ai-native/skills-and-subagents) |
| The agent built something nobody asked for | no goal or non-goals in the spec | write both | [Specs](/learn/markdown/ai-native/specs-and-plans) |
| A chatbot cannot find an answer that is in the docs | vague headings, or sections that need the page | name topics; make sections stand alone | [LLM docs](/learn/markdown/ai-native/llm-friendly-docs) |
| A customer email shows `**` and `##` | Markdown pasted into plain text | remove the marks | [Cleaning](/learn/markdown/ai-native/cleaning-ai-output) |