agent's markdown table parser failed, api reference layout broken

TL;DR

Stop splitting table rows on raw pipe characters. Pipes appear legitimately inside code spans, escaped pipes, and links, so a naive split shreds the row into the wrong number of cells. Fix: parse tables with a real markdown library, or normalize cells by masking code spans before splitting, and validate every row's cell count.

The error

agent's markdown table parser failed, api reference layout broken

Steps

1. Find a broken table in the generated reference and look at the source row. The break is usually a cell containing a code span with a pipe, like a type union, or an escaped pipe. Expected: you identify the exact cell whose pipe confused the splitter.

2. Replace the hand-rolled row splitter with a real markdown parser (markdown-it, remark, or mistune) and read table structure from its AST instead of splitting strings. Expected: the parser reports the correct cell count for every row.

3. If you must keep the custom splitter, mask code spans and escaped pipes before splitting: replace their contents with placeholders, split on the remaining pipes, then restore. Expected: rows with inline code split into the same cell count as the header.

4. Add a validation pass: every body row must have the same cell count as the header row, and every generated page gets re-checked after rendering. Expected: mismatched rows are flagged at build time, never published.

5. Regenerate the API reference. Expected: parameter tables align, code spans inside cells render intact.

Use this when

• API reference tables show misaligned columns or extra cells
• cells containing code with pipe characters render broken
• the agent wrote its own table parsing instead of using a markdown library

Not for this skill when

• tables parse fine but the content is wrong (a data issue)
• the layout breaks because of CSS, not parsing
• the source is RST grid tables, not markdown pipes (different parser)

Variant phrasings

• pipe in code span breaks markdown table parsing
• api reference parameter table misaligned
• custom table splitter mangles cells with escaped pipes
• markdown table cell count mismatch in generated docs

Why it happens

A pipe is both the table column delimiter and a legal character inside code spans, inline code, and escaped sequences. A regex or string split cannot tell the two apart, so any cell containing a union type, a shell pipe example, or an escaped pipe produces phantom columns.

Edge cases

• Tables inside blockquotes or lists: the parser must strip the prefix before counting cells.
• Multiline cells via HTML line breaks: keep them as one cell; do not split on the break.
• Right-to-left or CJK content: cell count validation is encoding-agnostic, so keep the check even when widths look odd.

Provenance

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