Parser reliability

Designing Markdown Tables for 80-Column Terminal Output

June 29, 2026 4 min read (updated September 17, 2026 )

Prepared and reviewed by the md2text maintainer. Parser-specific claims are checked against the public compatibility lab and automated regression suite.

Switching styles does not always make a wide table fit. In the reference example below, Grid ASCII occupies 104 display columns. Simple text reduces it to 98, which still exceeds an 80-column destination. Shortening the descriptions while preserving the option names and defaults brings the grid down to 57 columns. Simple then uses 51.

The before-and-after measurements include both Markdown sources and all three outputs. The options belong to a fictional CLI reference used as sample data. md2text is a browser tool and does not provide these command-line flags.

Start by measuring the whole row

Our original table has Option, Default, and Description columns. The longest description says Stores generated preview files until the next successful build. One verbose value sets the width of that entire column, including every short row below it.

The three normalized column widths are 17, 15, and 62. Grid borders and padding add ten more display columns:

17 + 15 + 62 + (3 x 3 + 1) = 104

Simple text replaces those ten columns of frame and padding with four separator spaces, giving 98. Unicode box keeps the same geometry as Grid ASCII, so it also measures 104. A border change cannot recover the 24 columns needed to fit the original grid.

Make the edit that preserves meaning

The repaired source keeps --cache-directory, .cache/previews, --retry-count, and 3. It changes Description to Purpose and uses Preview cache and Request retries as the values. That reduces the third column from 62 to 15 display columns.

Version	Grid ASCII	Unicode box	Simple text
Original descriptions	104	104	98
Short purposes	57	57	51
Columns saved	47	47	47

Move the omitted behavior into prose below the table: preview files are retained until the next successful build; a failed request is retried before an error is reported. The table remains a quick reference while the paragraph preserves the operational detail.

Do not abbreviate an actual option name simply to save space. A copied flag should still be valid. Shortening descriptive prose is usually less risky than changing identifiers, file paths, numeric values, or units.

Budget for the final destination

An 80-column-safe table can exceed the limit once it is pasted into surrounding syntax. A four-space indent and a // source-comment prefix consume seven more columns. The 57-column repaired grid becomes 64 columns; an exactly 80-column table would become 87.

Final width = table width + indent + prefix
Example: 57 + 4 + 3 = 64

Count any line-number gutter separately if it reduces the usable text area. Quoted email replies, nested Markdown lists, and narrow side panels have similar constraints. The converter measures the characters in its output, not the available pixels in another application’s layout.

Read health and diagnostics separately

The health summary reports whether the rendered text is at most 80 columns, between 81 and 120, or above 120. A width warning describes destination fit. It does not mean that the parser lost a cell.

Diagnostics describe structural uncertainty such as a missing cell or an ambiguous sentence after a table. Fix those first, then check width. Otherwise an apparently narrow result might simply be missing information you intended to include.

For a mixed document, the top-level maximum includes surrounding paragraphs. A long explanatory sentence can keep the document warning visible even when the table itself is narrow. With multiple tables, use the individual table summaries to distinguish table width from document width.

When shortening is not enough

Split the table when columns answer separate questions. A flag/default reference and a task/command reference are often easier to scan separately. Long URLs can move into a reference list. For a field that genuinely needs a paragraph, use a heading and prose instead of a fixed-width cell.

md2text does not automatically wrap or truncate long cells. That preserves the value you entered, but it means you must decide how to restructure an oversized table. The displayed 80-column threshold is a practical budget, not a universal guarantee for email or phones.

Reproduce the result

Open either measured example below, then switch among the three styles. The original should show 104, 104, and 98 maximum columns; the repaired version should show 57, 57, and 51. Copy the result into the real destination and add the indentation or prefix it needs there.

These are reproducible converter measurements, not measurements of a particular terminal emulator. For non-ASCII data, read the Unicode width guide; for the general padding formulas, see the style comparison.

Measured examples

Results below use the current md2text converter. Width is measured in display columns; output lines include borders and separator lines. These are constructed documentation examples, not tests of a particular email client or terminal.

Before: descriptions inside cells

This fictional CLI reference is too wide even after removing grid borders.

Markdown source

| Option | Default | Description |
|---|---|---|
| --cache-directory | .cache/previews | Stores generated preview files until the next successful build |
| --retry-count | 3 | Retries a failed request before reporting an error |

Measured output by style
Style	Max columns	Lines	80-col fit
Grid ASCII	104	7	May wrap
Unicode box	104	7	May wrap
Simple text	98	4	May wrap

Grid ASCII output

+-------------------+-----------------+----------------------------------------------------------------+
| Option            | Default         | Description                                                    |
+-------------------+-----------------+----------------------------------------------------------------+
| --cache-directory | .cache/previews | Stores generated preview files until the next successful build |
+-------------------+-----------------+----------------------------------------------------------------+
| --retry-count     | 3               | Retries a failed request before reporting an error             |
+-------------------+-----------------+----------------------------------------------------------------+

Try this Grid ASCII example

Unicode box output

┌───────────────────┬─────────────────┬────────────────────────────────────────────────────────────────┐
│ Option            │ Default         │ Description                                                    │
├───────────────────┼─────────────────┼────────────────────────────────────────────────────────────────┤
│ --cache-directory │ .cache/previews │ Stores generated preview files until the next successful build │
├───────────────────┼─────────────────┼────────────────────────────────────────────────────────────────┤
│ --retry-count     │ 3               │ Retries a failed request before reporting an error             │
└───────────────────┴─────────────────┴────────────────────────────────────────────────────────────────┘

Try this Unicode box example

Simple text output

Option             Default          Description                                                   
-----------------  ---------------  --------------------------------------------------------------
--cache-directory  .cache/previews  Stores generated preview files until the next successful build
--retry-count      3                Retries a failed request before reporting an error

Try this Simple text example

After: short descriptions, detail below

Keep the flags and defaults intact. Move retention and retry details into prose outside the table.