## 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
```text
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