Details
-
Bug
-
Status: Open
-
Major
-
Resolution: Unresolved
-
None
-
None
-
None
Description
For tables in our markdown documentation we typically do not use markdown tables (which are supported by the markdown renderer rdiscount), but instead add raw HTML tables to the document. As far as I can reconstruct this now, the motivation for this was that support for customizing the way entities are rendered; we are e.g., interested in adding class="table table-striped" to all tables for styling.
Ideally we should format in some markdown-friendly format extension, see e.g., https://talk.commonmark.org/t/tables-in-pure-markdown/81, https://github.com/gitlabhq/gitlabhq/blob/master/doc/user/markdown.md, https://michelf.ca/projects/php-markdown/extra/#table, https://help.github.com/articles/organizing-information-with-tables/, or http://pandoc.org/MANUAL.html#tables. It seems e.g., the following format is widely supported:
| First Header | Second Header | | ------------- | ------------- | | Content Cell | Content Cell | | Content Cell | Content Cell |
Adding raw HTML to markdown documents is suboptimal for a number of reasons, at least
- Not just the table structure, but all content in the table needs to be in raw HTML. This forces us to e.g., wrap in <code> tags instead of just ` like in the surrounding text. This appears to introduce additional cognitive load which leads to often poorly marked up tables.
- The whole promise of semantic markup languages like markdown is to separate semantic meaning from representation. Raw HTML tables break this severly.
- While many markdown renderers can output to different output formats, raw HTML limits the output formats which can be created.
It appears it should be possible to switch to another markdown renderer for the site, e.g., redcarpet which we could globally adjust to render tables in our preferred style, see https://github.com/vmg/redcarpet#and-you-can-even-cook-your-own.