Unauthoritative Pronouncements

The mdHatter Project

version -2.0.1

I needed to make a large table with multiple lines in a single cell and complete control over the formatting. Doing it with a WYSIWYG editor (Pages) provided some really terrible controls. It also injected all kinds of formatting that would take a significant amount of time to remove. I wanted to be able to enter it as simply as possible and looked to Markdown. Unfortunately, I found out that there are many approaches to tables for Markdown, and I didn’t like any of the methods I found. The tables they produced looked more like the ASCII art representation of a table. More importantly, none of them included allowances for multiple lines in a cell.

tl;dr

I liked the straight-forward examples of table formatting in HTML that I was seeing, but only in terms of structure. The tags were incredibly tedious, and it made it difficult to quickly reorder entries. The result was more legible than any of the Markdown solutions though. MultiMarkdown in particular utilizes and inscrutable series of pipes, underscores, dashes, and spaces to produce a table. It’s fine if you have a 2x3 table with cell content of mostly the same length, but if you need to put in a large amount of text in one cell and a small amount of text in the cell below it, you wind up with weird results.

|entry |entry|

|  OMG **ENTRY** HERE _VERY_ IMPORTANT | entry |

This is not ideal. And, you can’t have a line break <br> without killing the whole thing.

Back to HTML

As I said above, it’s mostly the tags, and keeping track of the order of tags, that makes raw HTML prohibitive for large tables that are hand coded. The structure inspired me to do this:

|

_entry
_entry
|
_OMG **ENTRY** HERE _VERY_ IMPORTANT
_entry

That’s easy to type out, and it is very legible, no matter how long or short a particular cell is because it’s delimited by the vertical pipe lines which represent the spots where <tr></tr>,<table border="0"></table>, and <tbody></tbody> tags will go in their proper order.

Save the Alignment for CSS

I disagree with the Markdown flavors that put allow you to control the text alignment in a cell with the number of spaces surrounding text. Text alignment should be left to CSS and whitespace shouldn’t be cluttering your table, or causing you to count the number of times you’re thinking about hitting the space bar. If the text alignment for a cell is so important than you should use the proper tags manually so at least you can find what you did later on.

Dependencies

The implementation I arrived at uses the Python Markdown module (easy_install Markdown) to facilitate the rest of the formatting in the document, line by line, and then an iterating trick to look at the lines before and after to insert the proper tokens for tables and code blocks. This isn’t ideal for a number of reasons, but primarily because you lose certain formatting functions that you get through reading the whole file. For instance, [TOC] table of contents don’t work when you’re reading a file line by line.

(Source: gist.github.com)