Wrap long lines in markdown tables

Question

My goal is to write documentation file that is easy to read in plain text form and in html form.

Problem is in using markdown tables. For example I have table with long strings:

| Name      | Description                                                                                                                  |
|-----------|------------------------------------------------------------------------------------------------------------------------------|
| some_name | Very very very long description for some_name property that should be easy to read even in plain text form even in html form |

This markdown generate normal HTML but it's impossible to read it in plaintext because of very long lines.

If I write something like this:

| Name      | Description                    |
|-----------|--------------------------------|
| some_name | Very very very long description|
|           | for some_name property that    |
|           | should be easy to read even in |
|           | plain text form even in html   |
|           | form                           |
|-----------|--------------------------------|

Then it's easy to read but it generate ugly html presentation.

Is there any way to wrap long lines in markdown tables?

Answer 1

It depends on which Markdown implementation you are using.

For example, Pandoc's multiline_tables and grid_tables both offer support for multiline cells, however, the more popular pipe_tables do not. Note that none of these are enabled by default, but must either be explicitly turned on via options, or get turned on as part of a Markdown variant. Let's look at each in turn:

multiline_tables

These tables use a blank line to separate each row.

------------------------------------------
Name       Description
---------- -------------------------------
some_name  Very very very long description
           for some_name property that
           should be easy to read even in
           plain text form even in html
           form  

other_name A second row
------------------------------------------

There are (at least) two problems with multiline_tables that I am aware of:

1. They are only supported by Pandoc. Therefore, if you want to have your Markdown processed by any other Markdown implementation, you cannot use them.
2. It can be a pain to edit the multiline text within a cell as you need to manually wrap the text in your text editor.

grib_tables

These are essentially a clone of Emacs table mode and a stricter implementation of restructuredtext's grid tables.

+------------+--------------------------------+
| Name       | Description                    |
+============+================================+
| some_name  | Very very very long description|
|            | for some_name property that    |
|            | should be easy to read even in |
|            | plain text form even in html   |
|            | form                           |
+------------+--------------------------------+
| other_name | A second row                   |
+------------+--------------------------------+

Each row is separated by a combination of - and + characters.

The known concerns with grid_tables are:

1. It is not supported by any other Markdown implementations (that I am aware of).
2. While it gets good editor support in emacs, you are stuck with emac, which may or may not be a good thing.

pipe_tables

In addition to Pandoc, these are supported by a large number of implementations, including PHP Markdown Extra, MultiMarkdown, GitHub Flavored Markdown, Python-Markdown^*, and Kramdown, among others.

| Name       | Description                                                                                                                  |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
| some_name  | Very very very long description for some_name property that should be easy to read even in plain text form even in html form |
| other_name | A second row                                                                                                                 |

Note that the syntax does not offer any way to define when one row ends and another row begins (unlike the other types of tables). As you cannot define the division between rows, then the only way it can work is if each line is its own row. For that reason, a row cannot contain multiple lines of text.

Finally, as Pandoc's documentation notes:

Since the pipes indicate column boundaries, columns need not be vertically aligned.

That being the case, it is easier to format the table in your text editor like this:

| Name       | Description  |
| ---------- | ------------ |
| some_name  | Very very very long description for some_name property that should be easy to read even in plain text form even in html form |
| other_name | A second row |

That certainly helps, and removes the need to manually wrap text. The long line is less than ideal. Nevertheless, it is the best option for most users due to the wide support across implementations.

MultiMarkdown's table documentation makes an interesting observation (emphasis in original):

MultiMarkdown table support is designed to handle most tables for most people; it doesn’t cover all tables for all people. If you need complex tables you will need to create them by hand or with a tool specifically designed for your output format. At some point, however, you should consider whether a table is really the best approach if you find MultiMarkdown tables too limiting.

---

^* Full disclosure: I am the maintainer of Python-Markdown