docs agent failed: unable to parse nested code fences in markdown docs

docs agent failed: unable to parse nested code fences in markdown docs

TL;DR

Make the outer fence longer than any fence inside it, or indent the inner blocks instead of fencing them. The parser saw the inner triple-backtick fence as the end of the outer block and everything after it turned into garbage. Four-backtick outer fences nest cleanly.

The error

docs agent failed: unable to parse nested code fences in markdown docs

Steps

1. Find the break. Open the failing page source and locate where an inner fenced block sits inside an outer fenced block.

Expected: you see an inner triple-backtick run nested inside an outer triple-backtick run, which is the ambiguous point.

1. Fix the source. Change the outer fence to four backticks with a matching four-backtick closing fence, or indent the inner code by four spaces instead of fencing it.

Expected: the page source has no fence run that could be misread as a closer.

1. Rebuild the docs and view the rendered page.

Expected: both code blocks render correctly and no content leaks into the prose around them.

1. Add a lint rule that flags fenced blocks containing a fence run of equal or shorter length inside them. A custom check or markdownlint rule works.

Expected: future nesting mistakes fail the docs build instead of shipping broken pages.

Use this when

• a markdown page renders broken right after adding an example that itself contains a fenced code block
• the rendered page shows raw backticks or swallows content below an example
• the docs agent generates docs about markdown and the output looks mangled

Not for this skill when

• fences are broken for other reasons, like an unclosed block with no nesting involved
• the parser fails on non-fence syntax
• the page renders fine but the code inside is wrong

Variant phrasings

nested code blocks break markdown rendering

Lengthen the outer fence past the longest inner fence.

docs show raw backticks after inner fence

The inner fence closed the outer block early; everything after it parsed as prose.

markdown example containing fenced block looks mangled

Use tilde fences for one level: they nest safely inside backtick fences.

Why it happens

Markdown fence parsing closes a block at the first fence run that matches the opening length. An inner fence of equal length always terminates the outer block early, so the rest of the outer content gets parsed as ordinary markdown and the page falls apart.

Edge cases

• Some renderers want the info string repeated on the longer fence. Test with your actual builder, not just the spec.
• Tilde fences nest safely inside backtick fences and vice versa, which helps when backtick counts get confusing.
• The agent that writes docs about markdown needs this rule in its writer instructions, or it will reintroduce the bug the next time it documents a fenced example.
• Triple-nested examples need each level longer than the one inside it. Count carefully or switch the innermost level to indented code.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_gSHYWN9KtiwyMEMohtrMfA