mesos-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Benjamin Bannier (JIRA)" <j...@apache.org>
Subject [jira] [Created] (MESOS-6729) Tables in documentation should not be in raw HTML, but instead markdown
Date Tue, 06 Dec 2016 11:11:35 GMT
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)

Mime
View raw message