Column alignment in tables in reStructuredText

A great feature of some Markdown flavours (PHP-Markdown Extra, Python markdown) is that they support column alignment in tables, using the colon character. That is, the contents of each column can be justified left, right or center independently. Other Markdown flavours do not support tables at all (CommonMark). ReStructured Text (RST) does support tables natively, however the alignment options are limited – you can align the whole table (all cells) left, right or center but not individual columns. There are many stackoverflow posts, with hacky solutions. You could use third-party sphinx extensions but standard docutils (rst2html5) and sphinx do not offer this facility.

Enter Emacs, the greatest text editor™. Emacs ships by default with a table mode. Due to historical reasons, the table syntax used by table-mode happens to be the same as the grid tables of RST. The table-mode not only supports column alignment, but also cell alignment! Each cell can be justified left, right or center independently. And each cell can contain any block-level element, such as blockquotes or code blocks. As a bonus, it supports exporting tables to HTML and LaTeX.

You don’t have to know or use Emacs. Just scroll below for copy-paste, callable from command-line.

The idea is to extract a table into its own file, say, table_diamonds.rst, convert it to HTML and save it to table_diamonds.htm. In the main RST file, instead of hardcoding the table itself, just use file inclusion:

.. include:: table_diamonds.htm

The .htm file must begin with .. raw:: html and the lines below it shall be indented, HTML auto-generated by Emacs. The HTML includes inline style commands to left-, right- or center-justify columns or cells, so nothing else is needed. You can of course add additional CSS styling to the main HTML document.

It is also extensible to LaTeX by replacing with:

.. include:: table_diamonds.tex

and .. raw:: latex; thus the source document (main.rst) and table_diamonds.rst will remain pristine. Emacs can generate LaTeX code too.

Alignment syntax

A normal RST table looks like this (source):

.. table:: Biggest diamond exporters

   +=======+============+=====================+
   | Rank  | Country    | 2021 (US$, billion) |
   +=======+============+=====================+
   |   1   | India      |        24.7         |
   +-------+------------+---------------------+
   |   2   | U.S.A      |        14.8         |
   +-------+------------+---------------------+
   |   3   | Hong Kong  |        14.0         |
   +-------+------------+---------------------+
   |   4   | Belgium    |        12.5         |
   +-------+------------+---------------------+

To align left, do not leave space between left vertical bar (|) and its contents. Similarly for aligning right. Leaving space on either side of vertical bars centers it. Modifying the above example so that the first column is center-aligned, second column is left-aligned and third column is right-aligned:

.. table:: Biggest diamond exporters (aligned)

   +=======+============+=====================+
   | Rank  |Country     |  2021 (US$, billion)|
   +=======+============+=====================+
   |   1   |India       |                 24.7|
   +-------+------------+---------------------+
   |   2   |U.S.A       |                 14.8|
   +-------+------------+---------------------+
   |   3   |Hong Kong   |                 14.0|
   +-------+------------+---------------------+
   |   4   |Belgium     |                 12.5|
   +-------+------------+---------------------+

which will be rendered as:

Biggest diamond exporters (aligned)
Rank	Country	2021 (US$, billion)
1	India	24.7
2	U.S.A	14.8
3	Hong Kong	14.0
4	Belgium	12.5

Emacs commands

You don’t have to type the vertical bars manually. Use M-x table-insert.

You don’t have to align columns manually. Use M-x table-justify-column.

If you’ve some table-like structure, place the cursor somewhere inside the table and M-x table-recognize to forcibly recognize the table and put it into table mode.

Once the table is recognized, you can tweak it as you please and export it to HTML using M-x table-generate-source; enter a filename table_diamonds.htm to save the generated code. This is the file that is .. include:: -ed above.

Automation

Even if you’re not an Emacs user, save this code in ~/.emacs.d/init.el. Start an Emacs session as usual (so that the lisp code is evaluated) and call it from a Linux command line:

emacsclient --eval '(self-table-rst-to-html "/home/user/somewhere/table_diamonds.rst")'

Just remember to pass full path to the .rst file. The output .htm file will be in same directory as the .rst. See table_diamonds.rst and table_diamonds.htm as an example.