Skip to content
Skills Library
Documents & office · Writing

markdown-table

/markdown-table

How to produce a Markdown table that is aligned and structurally valid — generate it from a Python script with a cell-count and escaping check, never by hand. Use when a page compares things across three or more columns, such as a type roster, an edge-case table, or a variant comparison.

Author
zio ↗
Repository
zio-skills ↗
Licence
Apache-2.0
Last repository change
27.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
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

How to produce a Markdown table that is aligned and structurally valid — generate it from a Python script with a cell-count and escaping check, never by hand. Use when a page compares things across three or more columns, such as a type roster, an edge-case table, or a variant comparison.

Original author description

How to produce a Markdown table that is aligned and structurally valid — generate it from a Python script with a cell-count and escaping check, never by hand. Use when a page compares things across three or more columns, such as a type roster, an edge-case table, or a variant comparison.

How it works

  1. Method — do not hand-align
  2. Syntax rules
  3. Content rules
  4. Output
  5. Worked shape
Original SKILL.md headings · 103 lines, 1,008 words
SKILL.md preview
---
name: markdown-table
description: How to produce a Markdown table that is aligned and structurally valid — generate it from a Python script with a cell-count and escaping check, never by hand. Use when a page compares things across three or more columns, such as a type roster, an edge-case table, or a variant comparison.
---

# Markdown Tables

This is the method behind writing-style rule 22 ("align table columns with spaces for readability").
The rule says the columns must line up; this says how to make them line up without eyeballing.

## Method — do not hand-align

Renderers ignore source alignment, but humans reviewing diffs do not — and a dropped or extra `|` is
invisible until the table renders wrong. Both problems are mechanical, so let a script handle them:

1. Write a small Python script holding the data as a header list plus a list of row lists — never as
   pre-formatted strings.
2. Compute each column's width as the widest cell in that column, then pad every cell to it.
3. Assert before emitting: every row has exactly `len(header)` cells, no cell contains a raw newline,
   and every `|` inside a cell is escaped. Print `TABLE CHECK: ok`, or the failures.
4. Assert on the emitted lines too: every one the same `len()`, every one the same `|` count. Print
   `LINE CHECK: aligned`, or the widths that differ.
5. Run it. Fix the **script** and rerun — never patch the rendered table.
6. Paste only the verified output.

Holding the data as rows rather than strings is what makes the first check possible: a row with a missing
cell is a `len()` mismatch, which an assertion catches and a reader does not.

The second check is what makes alignment a fact rather than a belief, and it must count characters with
`len()`. A width function of your own that treats some characters as two columns will agree with the
padding it produced — the check and the bug share an assumption, so the output passes while the source
is ragged. `len()` cannot do that, because it is what a diff, an editor and a byte count all use.

## Syntax rules

- Header row, then a separator row of plain `---` per column. Left is what a renderer does anyway, so
  an alignment marker on every column is noise: ✅ `|------|------|` ❌ `|:-----|:-----|`
- Add a marker only where a column needs something other than the default — `---:` to right-align a
  column of numbers, `:---:` to centre short flags. Mixed markers in one row are fine and are the signal
  that those columns were chosen deliberately.
- The separator row carries no padding spaces of its own: its dashes fill the whole cell, including the
  two columns the data rows spend on spaces either side. A column of width `w` gets `w + 2` characters
  between its pipes: ✅ `|----------|` ❌ `| -------- |`
- Escape `|` inside a cell as `\|`, **including inside backticks**, where it still breaks the table.
- Cells are single-line. Use `<br/>` for a forced break; a cell that wants a list or a code block means
  the table is the wrong container — use a definition list or headings.
- Docusaurus renders MDX, so `{` and `<` in a cell must be escaped or wrapped in backticks, or the
  parser reads them as JSX and the build fails.
- Prefer single-width characters. Emoji and CJK are ambiguous-width: they look padded to you and ragged
  to someone else. If a cell must contain them, pad by display width rather than `len()`.

## Content rules

- The first column is the key the reader scans — the thing they already know. Sort by it, or by the
  order the prose introduces.
- Every column must vary: ✅ a column whose values differ per row ❌ a column repeating one value, which
  belongs in the sentence above the table
- Three or more columns, or readers comparing across rows. Two columns of prose is a list:
  ✅ `| Method | Returns | Cost |` ❌ `| Method | What it does |` (write bullets)
- Header labels are short nouns — short enough not to widen the column past its data.
- No trailing "Notes" column absorbing whatever did not fit. If it does not fit a column, it is prose.
- Introduce the table with a sentence naming what to compare, and do not restate the rows underneath.

## Output

Paste the finished table only. Keep the script out of the page — it is scaffolding — and report its
`TABLE CHECK` line in your result so the next reader knows the table was verified rather than eyeballed.

## Worked shape

```python
header = ["Method", "Returns", "Cost"]
rows = [
    ["`record(name, by)`", "`Ledger`", "O(1)"],
    ["`tallyOf(name)`", "`Long`", "O(1)"],
    ["`absorb(that)`", "`Ledger`", "O(n)"],
]
align = [None, None, "right"]  # None is plain `---`; name one only where it is needed

bad = [(i, len(r)) for i, r in enumerate(rows) if len(r) != len(header)]
bad += [(i, "newline") for i, r in enumerate(rows) for c in r if "\n" in c]
bad += [(i, "unescaped |") for i, r in enumerate(rows) for c in r if "|" in c.replace(r"\|", "")]
print("TABLE CHECK: ok" if not bad else f"TABLE CHECK FAILED: {bad}")

width = [max(len(h), *(len(r[i]) for r in rows)) for i, h in enumerate(header)]

def rule(w, a):  # w + 2, because the separator also covers the spaces a data row pads with
    if a == "right":  return "-" * (w + 1) + ":"
    if a == "center": return ":" + "-" * w + ":"
    return "-" * (w + 2)

sep = [rule(w, a) for w, a in zip(width, align)]
line = lambda cells: "| " + " | ".join(
    c.rjust(w) if a == "right" else c.center(w) if a == "center" else c.ljust(w)
    for c, w, a in zip(cells, width, align)
) + " |"

out = [line(header), "|" + "|".join(sep) + "|", *(line(r) for r in rows)]
lens, pipes = {len(l) for l in out}, {l.count("|") for l in out}
print("LINE CHECK: aligned" if len(lens) == len(pipes) == 1
      else f"LINE CHECK FAILED: widths={sorted(lens)} pipes={sorted(pipes)}")
print("\n".join(out))
```

The `|`-escaping check deliberately strips `\|` first, so an already-escaped pipe passes and a bare one
fails — the failure that renders as a stray extra column.

Versions

The database has no other skills named markdown-table.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version cef0f833ab7e (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

  • 100markdown-tables
    Use when creating or formatting tables in markdown. Covers table syntax, alignment, escaping, and best practices.
  • 100markdown-table-discipline
    Enforces best practices for Markdown table construction. Invoke when deciding table vs list format, or when formatting multi-column data. Prevents visual noise, redundancy, and accessibility issues.
  • 100ascii-diagram
    How to produce an ASCII diagram that is actually aligned — generate it from a Python script with a width assertion, never by hand. Use when a page needs a box-and-arrow diagram, such as a module reference's "How They Work Together" section or a tutorial's data-flow picture.
  • 100markdown-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…

Feedback and reports

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