Hi all!
Victoria (@QuietMisdreavus) and I are excited to pitch an enhancement to Swift-DocC’s Markdown support. This will affect existing clients of Swift’s cmark-gfm fork who choose to opt into the enhancement – including Swift Markdown and Swift-DocC.
Introduction
Row and column spanning is a common tool documentation authors reach for when conveying complex information in a table but is currently unsupported in both CommonMark and GitHub Flavored Markdown. In keeping with the philosophy of Markdown, we’d like to enhance the Swift Project’s fork of GitHub Flavored Markdown to add support for this feature in a way that continues to be backwards compatible with standard Markdown parsers.
Proposed Solution
For row spanning specifically, there isn’t much prior art in commonly-used, shipping Markdown parsers for us to pull from. By researching existing discussions on the topic in the CommonMark forums, we’ve developed a solution that preserves Markdown’s philosophy of using punctuation characters to convey formatting in a way that is still readable in plain text and renders in a reasonable way with standard Markdown parsers. We propose adding the following syntax to Markdown tables: the “ditto mark”.
a pair of marks " used underneath a word to save space and show that the word is repeated where the marks are
The ditto mark is generally used in hand-writing as a shorthand to indicate that a given line should be the same as the one above. It’s often used in math since it can more clearly convey what is actually changing between two lines of an equation.
In a Markdown table it would be used for this same purpose – to indicate that the above cell contains information that should be conveyed in the current one.
Here’s an example of a Markdown table that includes row spanning with the new ditto syntax:
## Examples
| Sloth name | Sloth colors | Sloth powers |
| ------------ | ------------ | ------------ |
| Stormy | Gray | Wind |
| " | Light blue | Ice |
| " | Purple | Rain |
| Lava | Red | Fire |
| " | Orange | " |
| " | Black | " |
| Electric | Yellow | Lightning |
| " | White | Wifi |
The ditto mark would be escaped with \" to indicate that the quotation mark should be rendered literally.
For column spanning, we think adopting an existing syntax from MultiMarkdown is the best path forward:
To indicate that a cell should span multiple columns, then simply add additional pipes (|) at the end of the cell, as shown in the example. If the cell in question is at the end of the row, then of course that means that pipes are not optional at the end of that row…. The number of pipes equals the number of columns the cell should span.
In our example table that would look like:
## Examples
| Sloth name | Sloth colors || Sloth powers ||
| ------------ | ------------ | ------------ | ------------ | ------------ |
| Stormy | Gray || Wind ||
| " | Light blue || Ice ||
| " | Purple || Rain ||
| Lava | Red || Fire ||
| " | Orange || " ||
| " | Black || " ||
| Electric | Yellow || Lightning ||
| " | White || Wifi ||
Given that input, Swift-DocC would render the following table:
While, GitHub’s renderer would display the following:
We think introducing the new ditto mark syntax and enhancing the existing pipe syntax strikes a good balance of maintaining compatibility with existing Markdown tooling while bringing new features to Swift-DocC and other clients of the Swift Project’s fork of cmark-gfm.
Victoria has put together an implementation of this pitch in the swift-cmark repository.
Alternatives Considered
Alternative One
The primary alternative we’re considering to the above proposal is using the caret (^) symbol in place of the ditto symbol ("):
| Sloth name | Sloth colors | Sloth powers |
| ------------ | ------------ | ------------ |
| Stormy | Gray | Wind |
| ^ | Light blue | Ice |
| ^ | Purple | Rain |
| Lava | Red | Fire |
| ^ | Orange | ^ |
| ^ | Black | ^ |
| Electric | Yellow | Lightning |
| ^ | White | Wifi |
This symbol has come up in several other proposals on this topic so has the potential to be the more readable and commonly understood symbol. I think the ditto symbol is a better choice since it is already intended for this purpose in hand writing, while the caret symbol is generally used to represent an arrow. Additionally, the caret is already used in the Swift community to represent a custom attribute in an attributed string so overloading that punctuation further could lead to confusion.
We’re definitely interested in feedback on this point in particular.
Alternative Two
Instead of extending Markdown syntax further, we could create a new Swift-DocC @Table directive to support this kind of table layout. It’s likely we’ll still want something like this in the future since Markdown tables don’t support multi-line content. However, we think that row and column spanning is a common enough feature that it’s worth extending Markdown in a backwards compatible way to support it here without requiring folks to migrate to an entirely different syntax to achieve this behavior.
Alternative Three
We could also extend table syntax to support dividers between every row like so:
| Sloth name | Sloth colors | Sloth powers |
| ------------ | ------------ | ------------ |
| Stormy | Gray | Wind |
| | ------------ | ------------ |
| | Light blue | Ice |
| | ------------ | ------------ |
| | Purple | Rain |
| ------------ | ------------ | ------------ |
| Lava | Red | Fire |
| | ------------ | |
| | Orange | |
| | ------------ | |
| | Black | |
| ------------ | ------------ | ------------ |
| Electric | Yellow | Lightning |
| | ------------ | ------------ |
| | White | Wifi |
However, this format renders very poorly when processed with a standard Markdown parser. It would also require users to migrate to a much more verbose syntax when introducing spanning to a table.
