Benjamin Bannier created MESOS-6729:
---------------------------------------
Summary: Tables in documentation should not be in raw HTML, but
instead markdown
Key: MESOS-6729
URL: https://issues.apache.org/jira/browse/MESOS-6729
Project: Mesos
Issue Type: Bug
Components: documentation, project website
Reporter: Benjamin Bannier
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:
{code}
| First Header | Second Header |
| ------------- | ------------- |
| Content Cell | Content Cell |
| Content Cell | Content Cell |
{code}
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.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
