Skip to content
Skills Library
Documents & office · Review & audit

markdown-table-validator

/markdown-table-validator

Detect and fix Markdown (GFM) tables that won't render on GitHub or the VS Code preview — unescaped pipes inside cells, header/separator column-count mismatch, indented (code-block) tables, and misplaced alignment colons. Use when a markdown table renders as raw text, when cleaning LLM-generated docs in bulk, or when auditing a repo's tables before a commit. TRIGGERS - markdown table broken, table not rendering, fix markdown table, escape pipe in table, GFM table, table renders as text, validate markdown tables.

Repository
cc-skills ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/scan_markdown_tables.ts

What it does and when to use it

Detect and fix Markdown (GFM) tables that won't render on GitHub or the VS Code preview — unescaped pipes inside cells, header/separator column-count mismatch, indented (code-block) tables, and misplaced alignment colons. Use when a markdown table renders as raw text, when cleaning LLM-generated docs in bulk, or when auditing a repo's tables before a commit. TRIGGERS - markdown table broken, table not rendering, fix markdown table, escape pipe in table, GFM table, table renders as text, validate markdown tables.

Original author description

Detect and fix Markdown (GFM) tables that won't render on GitHub or the VS Code preview — unescaped pipes inside cells, header/separator column-count mismatch, indented (code-block) tables, and misplaced alignment colons. Use when a markdown table renders as raw text, when cleaning LLM-generated docs in bulk, or when auditing a repo's tables before a commit. TRIGGERS - markdown table broken, table not rendering, fix markdown table, escape pipe in table, GFM table, table renders as text, validate markdown tables.

How it works

  1. Why tables break (the one rule that matters)
  2. Quick start
  3. What it detects
  4. Output
  5. --fix heuristic (always review the diff)
  6. Relationship to the automatic guard
  7. References
  8. Post-Execution Reflection
Original SKILL.md headings · 93 lines, 657 words
SKILL.md preview
---
name: markdown-table-validator
description: Detect and fix Markdown (GFM) tables that won't render on GitHub or the VS Code preview — unescaped pipes inside cells, header/separator column-count mismatch, indented (code-block) tables, and misplaced alignment colons. Use when a markdown table renders as raw text, when cleaning LLM-generated docs in bulk, or when auditing a repo's tables before a commit. TRIGGERS - markdown table broken, table not rendering, fix markdown table, escape pipe in table, GFM table, table renders as text, validate markdown tables.
allowed-tools: Bash, Read, Edit
---

# Markdown Table Validator

Scan Markdown files for the structural problems that silently demote a GFM table
to a plain paragraph on GitHub / VS Code preview, and optionally auto-escape the
single most common cause (an unescaped `|` inside a cell).

> **Self-Evolving Skill**: This skill improves through use. If the detector
> misses a real broken-table case, the `--fix` heuristic guesses wrong, or a
> path/flag has drifted — fix this file (and the detector SSoT) immediately,
> don't defer. Only update for real, reproducible issues.

## Why tables break (the one rule that matters)

GFM ignores whitespace between pipes, so **alignment is never the cause**. What
breaks rendering is **structure** — overwhelmingly an **unescaped `|` inside a
cell**. GFM's table tokenizer treats a `|` as a column delimiter _even inside a
`` `code span` ``_, so a regex/code cell like `` `a | b | c` `` inflates that
row's cell count and the whole table collapses. The fix — escaping it as `\|` —
changes meaning, so **no formatter does it for you** (Prettier actively corrupts
such tables: prettier#10164 / #11410). This skill detects it and can apply the
escape under review.

## Quick start

```bash
SCAN="$(cc-plugin-root doc-tools)/skills/markdown-table-validator/scripts/scan_markdown_tables.ts"

# Report problems in one file (exit 1 if any render-breaking error)
bun "$SCAN" path/to/FILE.md

# Audit a whole tree
bun "$SCAN" "docs/**/*.md" "plugins/**/*.md"

# Opt-in auto-fix: escape over-count pipes, then re-align with prettier
bun "$SCAN" --fix path/to/FILE.md
prettier --write path/to/FILE.md
```

## What it detects

| Code                     | Severity | Meaning                                                                  |
| ------------------------ | -------- | ------------------------------------------------------------------------ |
| `column-overflow`        | error    | A row has more cells than the header → unescaped `\|` in a cell.         |
| `header-mismatch`        | error    | Header and separator row have different column counts → won't render.    |
| `indented-table`         | error    | Table indented ≥4 spaces → parsed as a code block.                       |
| `alignment-colon-in-row` | error    | An alignment token like `:--:` sits in a data row (misplaced separator). |
| `short-row`              | info     | Row has too few cells; GFM pads and `markdownlint --fix` repairs.        |
| `missing-blank-line`     | info     | No blank line before/after the table; the formatter auto-fixes.          |

Fenced code blocks (` ` ```) are skipped, so example broken tables shown
inside docs don't trip the scan.

## Output

Compiler-style `path:line: severity: message [code]`. Exit `0` when no **error**
remains (info nits never fail the run), `1` otherwise — usable as a gate.

## `--fix` heuristic (always review the diff)

For a row with more cells than the header, the genuine columns are assumed to be
the **first N**; every pipe beyond column N is treated as literal content and
escaped as `\|`. This exactly fixes the common case (regex/code in the last
cell) but can guess wrong when a pipe was a _genuinely missing_ delimiter — so
review the diff, then run `prettier --write` to re-align.

## Relationship to the automatic guard

This skill is the **manual, repo-wide** counterpart to the per-edit
`itp-hooks` PostToolUse guard (`posttooluse-markdown-table-guard.ts`), which
reminds Claude to fix the same errors the moment a `.md` file is written. Use
the skill to clean **existing** docs in bulk; the hook prevents **new**
breakage. Both share the same detection algorithm (SSoT:
`plugins/itp-hooks/hooks/lib/markdown-table-detector.ts`).

Suppress the per-edit hook on a file by adding a comment containing `MD-TABLE-OK`.

## References

- [algorithm.md](./references/algorithm.md) — the detection algorithm + the pipe-escaping rationale.

## Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. **Locate yourself.** — Find this SKILL.md's canonical path before editing.
1. **What failed?** — A missed broken table or a false positive → fix the detector (`markdown-table-detector.ts`) and its mirror here.
2. **What worked better than expected?** — Promote to recommended practice.
3. **What drifted?** — Keep the self-contained scanner copy in parity with the itp-hooks detector SSoT.
4. **Log it.** — Note the trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.
Files in this package (3)
  • SKILL.md 5 KB
  • references/algorithm.md 4 KB
  • scripts/scan_markdown_tables.ts 13 KB

Versions

The database has no other skills named markdown-table-validator.

Database snapshot: 13.11.2026 · package version cac7d209be9e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 84html-to-markdown-extracting-tables
    Use when extracting tabular data from HTML. Covers GFM Markdown tables, the structured tables array (grid cells plus pre-rendered markdown), and HTML line breaks in table cells.
  • 100html-to-markdown-extracting-tables
    Use when extracting tabular data from HTML. Covers GFM Markdown tables, the structured tables array (grid cells plus pre-rendered markdown), and HTML line breaks in table cells.
  • 100markdown-tables
    Use when creating or formatting tables in markdown. Covers table syntax, alignment, escaping, and best practices.
  • 100docx-convert
    [Document Processing] Use when converting between Word DOCX and Markdown (GFM, math rendering). --to={markdown|docx}.
  • 100docx-convert
    [Document Processing] Use when converting between Word DOCX and Markdown (GFM, math rendering). --to={markdown|docx}.
  • 100xberg-extracting-tables
    Use when extracting tabular data from PDFs, spreadsheets, or images. Covers layout-aware table detection, table model selection, output formats (markdown / JSON cells), and known limits.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.