Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Feature Request: Tables #73
Tables are used very often to help explain information that would requires multiple paragraphs into a clear concise 2d layout. The issue with making this feature optional means it won't be fully widespread. And stuff like tables and anchors are common enough to be a core standard.
A common complaint I understand about tables in markdown variants that attempts to implement this, is that it is hard to maintain. So here is some ways I think it can be simplified from "Markdown Extra" syntax for this effort.
This is Markdown Extra Syntax for tables:
First example (Compress the pipe headers):
To indicate a field is a header you use
Second Example ( CSV Input):
The second issue, is that people find it hard to have to deal with formatting the pipes. If alignment of cell data is of no concern to the user, then we should use CSV data as the inspiration.
I'm a big fan of CSV data, due to how easy it is to type. The ease of use comes from sticking to csv which most people use already, and combining it with a simplified table header.
If you still need alignment control for each cell, then you can just use the previous (but simplified) pipe tables shown above using
example data from: http://en.wikipedia.org/wiki/Comma-separated_values
Essentially, just treat pipes as 'optional' for the actual cell data (which is the field that gets modified most often anyway (compared to the header). This way, we can avoid too much formatting, and heck if you are lazy, you could just remove whitespaces and it shall still be very maintainable like so:
The second approach is my preference. Since I believe markdown is about getting formatting out of the way of your writing.
Multimarkdown expands on markdown extra's pipe tables and allows for grouping (only
About your suggestion though. In my opinion, I think your method to suppress the pipe headers and include header/alignment information within the header cells themselves is ugly since it requires that every cell below adds more spaces to align 'prettily'. By pretty, I mean the first letters directly aligning underneath each other. I know it doesn't affect the final output since it's a pipe table, but one of the points of markdown is to be able to read the plain text fairly easily as well. These types of headers I find are much harder to read than simply including a row of hyphens. I don't think it's that difficult to include the row of hyphens.
I agree that csv is nice, but it is of my understanding that csv data is usually in separate files by themselves (i.e. not intermixed/embedded in normal text)? My point is that, how would you differentiate between a paragraph with commas and a csv table as you put it (that doesn't need alignment information in the header, as in the header also uses commas to separate cells, and the table doesn't have an alignment hyphen row)? (Remember blank lines separate paragraphs, not simply newlines.) I believe pipes are differentiated (for example between a paragraph with pipes and a pipe table in pandoc markdown) by the presence of the hyphen row.
Also, isn't the pipe character fulfilling exactly the same purpose as a comma in your csv tables, as in 'pipe separated values'? I know pipe is harder to type than comma, but I'd prefer to escape pipes in my table than every comma (for when you actually need to use a comma in a cell, which is usually much more common than pipes).
So you mean that the
Hmmm... I can see what you mean. I personally see the maintenance of adjusting the header with my method to be much easier however. But I can understand the need for aesthetic pleasure of textual presentation. So I will concede the need for "compressed piped headers" for standard pipe tables, and I can see how
However in the case of CSV tables, compressed pipe tables is a must. Specifically for the ease of adjusting 'table headers' length, without having to readjust every column.
While csv data is usually treated as a separate file, making it inline as part of a csv table will not conflict with any other syntax. This is because a csv table, is not a table without the "compressed pipe table header", which you can think of as the 'initializer' of the table. Plus there is no point making it any more complex, since you can't format csv in any complex manner.
I have considered that the pipe table is doing the same purpose as the csv comma, however I would prefer the flexibility in not needing to worry about alignment of commas as much as pipes (pipes is much more obviously ugly when unaligned). And would appreciate the flexibility of not needing to adjust most copy pasted csv data.
I think the difference between us really depends on the situation. Do you want pretty tables? Or do you want just good enough, and fast to maintain. Markdown is about being pretty and fast to type, which sometimes is hard to do (but is way better than XML regardless in both the pretty and fast type criteria).
So in summery after taking your point into consideration:
Previously I wanted a gradient of flexibility to maintainability. But I think the best approach is either go "Maximum Flexibility" or "Maximum Maintainability".
edit (simplified csv styled table form):
You're right. The reason I want the prettiness is because my editor (vim) makes prettily aligned tables very easy to maintain, so why not have both? I would probably prefer the more practical option of easy to type if that wasn't the case though. And of course, I'm not arguing for the requirement of an editor that aids in such maintainence, since that sort of defeats the purpose of markdown in the first place (we want the spec to be irrespective of any editor), I'm just trying to convey why I thought it was sub-optimal, but obviously I was only considering myself.
So I guess the key point is that "pipes are much more obviously ugly when unaligned", as compared to commas. I hadn't considered that previously, but I agree. And that in addition to clarifying that csv tables require the 'compressed pipe table header', I'd agree for your csv table suggestion as an option for table syntax. That is, provided pipe tables are also included… (continued below)
So I'm not sure if talk.standardmarkdown.com will still be up? So I'll put the following here for now, instead of at http://talk.standardmarkdown.com/t/tables-in-pure-markdown/81/27 which is where it probably should be (you may want to reference this over there though just in case).
I'd also argue for the inclusion of the three other types of tables supported by pandoc markdown, as well as support of using a
So now in summary:
This way we could probably satisfy quite a lot of needs, while still retaining fairly simple and readable syntaxes (with varying degrees of flexibility and maintainability).
Of course, I may have easily overlooked a conflict or something in supporting five different table syntaxes, or overlooked a difficult implementation detail so feel free to bring up such a case. This is only a suggestion for the future; for whenever john wants to deal with tables.