Render Gotchas

By the Syncfusion DevTutorials team · Last updated October 19, 2026

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.

What you will learn

Diagnose a Markdown rendering or agent-file problem from its symptom

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

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
Lines run together into one paragraph	a single line break does not start a new line	blank line between paragraphs	Headings
An address prints on one line	no hard line break	end each line with `\`	Headings
A line break vanished after saving	the editor removed two trailing spaces	use `\` instead	Headings
A sentence became a big heading	`---` right under it	blank line above `---`	Headings
A section is missing from the page menu	it is a bold line, not a heading	use `##`	Headings
` text ` shows the stars	spaces just inside the stars	`text`	Headings
A heading link stopped working	the heading was renamed	update the `#anchor` links	Links

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
One list shows as several	the bullet mark changed	one mark everywhere	Lists
Numbering restarts, or "1" twice	an unindented paragraph ended the list	indent it under the step	Lists
A code block breaks the list	the fence is not indented	indent it to the step's text	Lists
A sentence starting with a year became a list	`2023.` looks like a list number	`2023\.`	Lists
`[ ]` shows as text	task lists are GFM-only	a GFM renderer, or words	Lists

Links and Images

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

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
A paragraph shows as code	it starts with four spaces	remove the leading spaces	Code
An example fence closes the outer block	both use three backticks	four backticks outside	Code
No colours in the code	no language hint	```bash, ```json …	Code
A copied command fails with `$: command not found`	the `$` prompt was copied	remove the prompt	Code

Tables

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

Escaping and HTML

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

A frontmatter error to read

---
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
The agent runs the wrong test command	no exact commands	a `## Commands` section	AGENTS.md
Claude Code ignores `AGENTS.md`	a `CLAUDE.md` exists without the import	`@AGENTS.md` in `CLAUDE.md`	AGENTS.md
A skill is never used	vague description, or no "when"	what it does, when, and when not	Skills
A skill is used for the wrong tasks	description too broad	specific words and "Do not use for …"	Skills
A skill or subagent does not appear at all	broken frontmatter, or a missing field	quote values; add `name` and `description`	Skills
The agent built something nobody asked for	no goal or non-goals in the spec	write both	Specs
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
A customer email shows `**` and `##`	Markdown pasted into plain text	remove the marks	Cleaning