Text tables: ASCII, Unicode and reStructuredText

Kinds of text tables

ASCII tables

+---------+---------------+-------+
| Planet  | Diameter (km) | Moons |
+---------+---------------+-------+
| Mercury |          4879 |     0 |
+---------+---------------+-------+
| Venus   |         12104 |     0 |
+---------+---------------+-------+
| Earth   |         12756 |     1 |
+---------+---------------+-------+
| Mars    |          6792 |     2 |
+---------+---------------+-------+

These use only +, - and |, which every font and every program has. It is the safest kind: it looks the same in an old terminal, in an e-mail and in a source file. The same table is a reStructuredText grid table when the line under the header is drawn with =.

Unicode box-drawing tables

╔═════════╦═══════════════╦═══════╗
║ Planet  ║ Diameter (km) ║ Moons ║
╠═════════╬═══════════════╬═══════╣
║ Mercury ║          4879 ║     0 ║
╠═════════╬═══════════════╬═══════╣
║ Venus   ║         12104 ║     0 ║
╠═════════╬═══════════════╬═══════╣
║ Earth   ║         12756 ║     1 ║
╠═════════╬═══════════════╬═══════╣
║ Mars    ║          6792 ║     2 ║
╚═════════╩═══════════════╩═══════╝

┌─────────┬───────────────┬───────┐
│ Planet  │ Diameter (km) │ Moons │
├─────────┼───────────────┼───────┤
│ Mercury │          4879 │     0 │
│ Venus   │         12104 │     0 │
│ Earth   │         12756 │     1 │
│ Mars    │          6792 │     2 │
└─────────┴───────────────┴───────┘

Unicode has characters for lines and corners, single (─ │ ┌ ┼) and double (═ ║ ╔ ╬). The lines join, so the table looks drawn rather than typed.

These tables need a fixed-width font that has the box-drawing characters. A font without them takes them from another font, which is usually wider or narrower: the border lines then do not line up with the rows of text, or show gaps. Old programs may show boxes or question marks instead. Fonts that have the characters include Consolas and Cascadia Mono (Windows), Menlo (macOS), DejaVu Sans Mono (Linux) and JetBrains Mono. When you do not know the reader's font, as in an e-mail or a file that others open, use an ASCII table.

Tables without lines

Planet   Diameter (km)  Moons
-------  -------------  -----
Mercury           4879      0
Venus            12104      0
Earth            12756      1
Mars              6792      2

Only spaces between the columns, and a line under the header. This is the kind that command line tools print, and the easiest to read in a long list. It is also the easiest to break: one cell longer than its column moves the rest of the row.

Why the columns line up, and when they do not

The columns line up because each character takes the same width: a fixed-width, or monospace, font. Code editors, terminals and code blocks use one. Most other text does not: in a proportional font, i is narrower than W, and the lines of the table come apart.

• Show the table in a fixed-width font. In Markdown and chat programs, put it in a code block (``` on the lines before and after it). In HTML, put it in a <pre> element. In Word, choose a font such as Consolas or Courier New. For a Unicode table, the font must have the box-drawing characters.
• Use spaces, not tabs. A tab moves the text to the next tab stop, and programs set the stops at different places (4 or 8 characters).
• Wide characters. Chinese, Japanese and Korean characters, and most emoji, take the width of two letters in a fixed-width font. A table must count them as two, or the lines of their rows stick out. Our generators do. Even then, some fonts draw emoji a little wider or narrower, so leave emoji out of text tables when you can.
• Many e-mail programs show plain text e-mails in a proportional font. A text table may not line up there. In an e-mail, use an HTML table.

Where to use a text table

• Code comments and documentation strings: a table of values, states or options next to the code that uses them.
• Plain text files: README.txt files, notes and logs.
• Terminal output of scripts and command line tools.
• Chat: Discord, Slack, Telegram and WhatsApp do not show Markdown tables, but they show a text table in a code block. See Tables in Discord, Slack and WhatsApp.
• Forums and Stack Overflow: in a code block, where the site has no tables.
• Python documentation and other reStructuredText documents, where the text table is the table's code.

A text table is hard to change by hand: when a cell gets longer, every line of its column must change. Keep the data somewhere else (a spreadsheet, a generator, a script) and draw the table again.

Tables in reStructuredText and Sphinx

reStructuredText (reST) is the markup of Python's documentation and of Sphinx. Its tables are text tables: the text you see is the code. A grid table can merge cells:

+---------+--------------------------------+
|         | Size                           |
| Planet  +---------------+----------------+
|         | Diameter (km) | Mass (10²⁴ kg) |
+=========+===============+================+
| Earth   | 12756         | 5.97           |
+---------+---------------+----------------+
| Mars    | 6792          | 0.642          |
+---------+---------------+----------------+

• The + signs must be one under the other, and each | under a +. One character out of place makes the error Malformed table.
• A line of = separates the header rows from the body.
• A merged cell is a cell without the lines inside it: Size has no + in the middle of its top line, and Planet has no line under its first row.
• reST has no alignment. The text of each cell starts at the left in the HTML, whatever the spaces in the code are.

A simple table is shorter to write. The lines of = set the columns: a column is as wide as its run of =.

=======  =============  =====
Planet   Diameter (km)  Moons
=======  =============  =====
Mercury  4879           0
Venus    12104          0
Earth    12756          1
Mars     6792           2
=======  =============  =====

Only the last column's text can be longer than its line of =. The first column cannot have empty cells (an empty first cell continues the row above).

A table that changes often is easier to keep as a csv-table (or a list-table). It has no lines to keep in line, and it has a caption:

.. csv-table:: The inner planets
   :header: "Planet", "Diameter (km)", "Moons"
   :widths: auto

   "Mercury", 4879, 0
   "Venus", 12104, 0
   "Earth", 12756, 1
   "Mars", 6792, 2

In our editor In the Text Tables Generator, select Use reStructuredText syntax. The generator writes a grid table, with the merged cells, and keeps the + and | signs in line for you.

Convert text to a table

You have text with the data of a table, one row on each line, and you want a real table.

In our generators

In any of our generators, select File › Paste table data, paste the text and click Load. These kinds of text become a table:

• columns separated by tabs, which is what you copy from a spreadsheet;
• columns separated by commas or semicolons (CSV);
• an ASCII table with +, - and |, like the first table in this guide, with its merged cells;
• a Markdown or MediaWiki table, or HTML code of a table.

Columns separated by spaces are not split. Replace the spaces between the columns with tabs first, or use a spreadsheet as below. Then make the table in the format that you need: LaTeX, HTML, Markdown or a text table.

In Microsoft Word

1. Put each row on its own line, with the same separator between the cells: a tab, a comma or another character.
2. Select the lines and select Insert › Table › Convert Text to Table.
3. Under Separate text at, choose the separator and click OK.

In LibreOffice Writer, it is Table › Convert › Text to Table.

In Excel and Google Sheets

Paste the text in the first column. In Excel, select the column and select Data › Text to Columns. Choose Delimited for a separator, or Fixed width for columns lined up with spaces: Excel then splits the text where you click. In Google Sheets, select Data › Split text to columns.

Google Docs cannot convert text to a table. Make the table in Google Sheets, copy its cells and paste them in the document.

Convert a table to text

• Word: click in the table and select Table Layout › Convert to Text (Layout › Convert to Text in older versions). Choose tabs, commas or another separator. This gives one line for each row, not a drawn table.
• Excel: File › Save As with the type Text (Tab delimited), or Formatted Text (Space delimited) for columns lined up with spaces.
• A drawn table: copy the cells from Excel, Google Sheets or Word and paste them in the Text Tables Generator. It draws the lines.

Make text tables with code

To print a table from a program, use a library rather than counting spaces yourself:

# Python, with the tabulate package
from tabulate import tabulate

rows = [['Mercury', 4879, 0], ['Venus', 12104, 0]]
print(tabulate(rows, headers=['Planet', 'Diameter (km)', 'Moons'], tablefmt='grid'))
# tablefmt='simple_grid': lines of box-drawing characters; 'rst': a reST simple table

# Linux and macOS: line up the columns of a CSV file
column -t -s, planets.csv

# PostgreSQL's psql: draw the result's table with box-drawing characters
\pset border 2
\pset linestyle unicode

Other languages have such libraries too, for example console.table() in JavaScript, which prints an array as a table in the browser's console and in Node.js.

Make the table without drawing it

In our Text Tables Generator, you type the cells in a grid, as in a spreadsheet, and it draws the table:

• Merge cells with the merge button on the toolbar. The table leaves out the lines inside the merged cell.
• Align the text of the selected cells with the toolbar's alignment buttons.
• Wrap long text: drag the right edge of a column's header to make the column narrower. The text of its cells breaks into lines at spaces. Drag it wider to join the lines again.
• Box-drawing characters: select Use Unicode symbols for table borders.
• reStructuredText: select Use reStructuredText syntax.

Click Copy to clipboard and paste the table in a fixed-width place: a code block, a code comment, a terminal.