markdown table with long lines

Question

I am using markdown in order to create a table. My Description column contains very long texts and therefor it looks very bad on the markdown file when I wrap lines:

Argument            | Description |
--------            | ----------- |
appDir              | The top level directory that contains your app. If this
option is used then it assumed your scripts are in |a subdirectory under this path. This option is not required. If it is not specified, then baseUrl below is the anchor point for finding things. If this option is specified, then all the files from the app directory will be copied to the dir: output area, and baseUrl will assume to be a relative path under this directory.  
baseUrl             | By default, all modules are located relative to this path. If baseUrl is not explicitly set, then all modules are loaded relative to the directory that holds the build file. If appDir is set, then baseUrl should be specified as relative to the appDir.
dir                 | The directory path to save the output. If not specified, then the path will default to be a directory called "build" as a sibling to the build file. All relative paths are relative to the build file. 
modules             | List the modules that will be optimized. All their immediate and deep dependencies will be included in the module's file when the build is done. If that module or any of its dependencies includes i18n bundles, only the root bundles will be included unless the locale: section is set above. 

I want to wrap lines since it is more readable for me.
Is there a way to make the table more readable for the editor?

Erasure

FWIW: Mediawiki "markup" has a more flexible syntax that allows more than one text-line per table row, but it's slightly less compact. – Nina

This is impossible with the Bitbucket parser: I wanted to do the same with a readme.md file, but Bitbucket's docs state unambiguously: "You can only put simple lines in a table." (source here) – Moult

Answer 1

I believe @Naor is right: You must use HTML to create line breaks, though that is not demonstrated in the answer. And the full table code displayed is not strictly necessary: To achieve a line break you only need double space or <br /> tag. From the Markdown spec:

Markdown supports “hard-wrapped” text paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type’s “Convert Line Breaks” option) which translate every line break character in a paragraph into a <br /> tag.

When you do want to insert a <br /> break tag using Markdown, you end a line with two or more spaces, then type return.

Note that I had to add code wrappers to the text because the SO-flavored Markdown requires HTML break tags are escaped - so we know <br /> works.

But, if you want to do something a bit more complex, like I am* you can set various properties with HTML like so:

<table width="300">
  <tr>
    <td> This is some text </td>
    <td> This is some somewhat longer block of text </td>
    <td> This is some very long block of text repeated to make it even longer. This is some very long block of text repeated to make it even longer. This is some very long block of text repeated to make it even longer.  </td>
  </tr>
</table>

I tried adding style="width:75%" to the <td>s, to no affect.

*I should note I came across this because I am having similar problems writing code within tables using GitHub-flavored Markdown, which is very painful. But I'm noting this because it should color the examples I give: Any thing I say 'works' or 'doesn't work' comes from that environment.

EDIT: It might be further worth noting this is irrelevant if you have code blocks within your table. This isn't an issue with Markdown though: HTML <code></code> blocks cause the table to stretch.

Pumpernickel

I think you missed the main point of the original question. The goal isn't to impact the final rendering of the markdown, it's to control the way the input text looks. The <br/> thing will insert a hard line wrap in the final rendering, but the OP was asking to be able to wrap the input file so the lines in it aren't super long and hard to read. – Lambaste

Answer 2

There's another option. Since the philosophy is that Markdown is supposed to be lightweight, not a markup language, and intended for natural human consumption (in contrast to SGML/HTML-style formats), I believe it's fine and natural to fall back to ASCII art for special cases.

For this particular task, character art is natural. Thus, just indent your table with four spaces, format it nicely for readability, and Markdown will just treat it as pre-formatted text, and both sides can stop fighting each other.

For example:

|  Sequence   | Result                                                        |
|-------------|---------------------------------------------------------------|
| `a?c`       | Matches `abc`, `axc`, and `aac`. Does not match `ac`, `abbc`, | 
|             | or `a/c`.                                                     |
|-------------|---------------------------------------------------------------|
| `a*c`       | Matches "ac", "abc" and "azzzzzzzc". Does not match "a/c".    |
|-------------|---------------------------------------------------------------|
| `foo...bar` | Matches "foobar", "fooxbar", and "fooz/blaz/rebar". Does not  |
|             | match "fo/obar", "fobar" or "food/bark".                      |
|-------------|---------------------------------------------------------------|
| `....obj`   | Matches all files anywhere in the current hierarchy that end  |
|             | in ".obj". Note that the first three periods are interpreted  |
|             | as "...", and the fourth one is interpreted as a literal "."  |
|             | character.                                                    |
|-------------|---------------------------------------------------------------|

... and done.

Spool

Warning for quick readers! Don't use this one if you need to get an HTML table namely. This one is to generate a kind of ASCII-art table. Using it ouside four space indented block (or ```-wrapped block in GFM), you'll get a separate tr for each line (and a separate tbody after each hyphen line) – Kiss

This breaks when viewed on mobile or any small screen/window. – Lafferty

Thanks for this, Steve. Shocking that MD can't just take this very table (unindented, of course) and render it in HTML. – Rittenhouse

This is not and answer for the original question. Everyone know you can go plain ascii with 4 spaces or the 3 backticks. – Meteorite

Answer 3

Sadly you must use HTML for this

<table>
<tr>
<th>Argument</th>
<th>Description</th>
</tr>
<tr>
<td>appDir</td>
<td>The top level directory that contains your app. If this option is used then
it assumed your scripts are in</td>
</tr>
<tr>
<td>baseUrl</td>
<td>By default, all modules are located relative to this path. If baseUrl is not
explicitly set, then all modules are loaded relative to the directory that holds
the build file. If appDir is set, then baseUrl should be specified as relative
to the appDir.</td>
</tr>
<tr>
<td>dir</td>
<td>The directory path to save the output. If not specified, then the path will
default to be a directory called "build" as a sibling to the build file. All
relative paths are relative to the build file.</td>
</tr>
<tr>
<td>modules</td>
<td>List the modules that will be optimized. All their immediate and deep
dependencies will be included in the module's file when the build is done. If
that module or any of its dependencies includes i18n bundles, only the root
bundles will be included unless the locale: section is set above.</td>
</tr>
</table>

Daytime

I try to avoid this.. What is the point using html.. Isn't any char that marks next line is continue the current line? – Erasure

Answer 4

If you want this to be pretty just for preview or html export, add a <br> where you want a line break

| table | column         |
| ---   | ---            |
| row1  | line1<br>line2 |
| row2  | other          |

Arezzo

Answer 5

Hi I was wondering the same thing. I needed this for a documentation file and this is the way how I'm dealing with this:

| key | description                        |
| --- | ---                                |
| foo | bla bla blabla bla blabla bla bla  |
|     | bla bla blabla bla bla bla bla bla |
| bar | something else bla                 |

I agree with Sam in question above that Markdown suppose to be "Hard-wrapped" language and there for this is cheating (I guess that's not a valid Markdown). But for example in several Github projects README.md files I saw people wrapping list items like this:

 * foo
 * bla bla bla bla bla bla bla bla bla bla 
   bla bla bla bla bla bla bla bla bla

Also my College pointed out that http://www.tablesgenerator.com/markdown_tables was wrapping table similar way (thanks Tom)

So what I think is ok to use my example if you are doing something that will not be parsed (like Github documentation) but you should not wrap if you're doing some Markdown to HTML parser or Cucumber test table.

But I may be wrong

Drue

this table variant will generate a separate tr for the second "bla bla" line (at least, for Jekyll/gh-pages and dillinger.io) ` <tr> <td> </td> <td>bla bla blabla bla bla bla bla bla</td> </tr>` – Kiss

I believe Octopress has the same parsing behavior – Kiss

Answer 6

This isn't a short cut but a formatting option:

Instead of doing:

| TABLE  | NUMBER | RELATIONSHIPS |
| ------ | ------ | ------------- |
| TABLEA | NUM001 | TABLE2, TABLE4, TABLE7 |
| TABLEB | NUM002 | TABLEA |

You could do:

| TABLE  | NUMBER | RELATIONSHIPS |
| ------ | ------ | ------------- |
| TABLEA | NUM001 | TABLE2        | 
|        |        | TABLE4        |
|        |        | TABLE7        |
| TABLEB | NUM002 | TABLEA        |

and simply leave blank spaces in the columns that don't have multi-line data. And a decent code editor can help assist with a lot of the formatting so you don't manually need to enter more than one space.

Dogma

This is not a solution since it creates a new row for TABLE4 and another for TABLE7 :/ – Rune