Incompatible Markdown
Quick question. Are these two html blocks equivalent?
<table>
<tr>
<th>Product</td>
<th>What it's good for</td>
<th>When to avoid/limitations</td>
</tr>
<tr>
<td>Spinnaker<br>[Docs](http://docs/for/spinnaker)</td>
<td>Services on K8s</td>
<td></td>
</tr>
<tr>
<td>Batch API<br>[Docs](https://docs/for/batch.html)</td>
<td>Batch Jobs</td>
<td>Not SparkSQL</td>
</tr>
</table>
and
<table>
<tr>
<th>Product</td>
<th>What it's good for</td>
<th>When to avoid/limitations</td>
</tr>
<tr>
<td>
Spinnaker<br>[Docs](http://docs/for/spinnaker)</td>
<td>Services on K8s</td>
<td></td>
</tr>
<tr>
<td>
Batch API<br>[Docs](https://docs/for/batch.html)<br></td>
<td>Batch Jobs</td>
<td>Not SparkSQL</td>
</tr>
</table>
According to the browsers I’ve tried, they are. But put them in a markdown file and things get interesting. Throw doxygen into the mix and it gets even weirder.
According to the W3C, whitespace inside tags is generally collapsed. LF and CRLF are mostly ignored, and browsers all (pretty much) do the same thing. That’s because it’s a standard. Yes, Microsoft did embrace, extend, extinguish, and IE6 became a standard unto itself, and now chromium is the standard, but at least you know what to expect.
In the case of Markdown, not so much. First, it’s not a standard, in any of the standard senses. There’s no governing body, there are no validation tests, and there are lots of flavors. There was (is?) an attempt to create a standard, but I think it’s a little too late for that.
With markdown, # is the big heading. Then you can have some number of them (depending on the implementation) of smaller headings. Surrounding your text
with backticks ` generally gets you inline code, _ gets italics, ** gets bold, and sometimes, ~~ gets you strikethrough. There’s a way to
do links. You can use ° to make bullet lists, and putting three backticks ``` before and after lines of code is a code block. And there are
usually tables. Generally defined by an arcane series of -s and |’s, with some :s thrown in to
make justification suggestions.
Beyond that it gets weird. Sometimes you can tell the code block what language you’re writing and it will do some syntax highlighting. Some of the format
specifiers can be nested (italic strikethrough), but others can’t. Then there are flavors of Markdown. Phab adds icons, images,
and internal references. Github has its version, as does Doxygen.
One thing I’ve never been able to figure out is lists in tables cells in pure Markdown. I’ve been able to do it using embedded HTML in markdown, which both
doxygen and GitHub support. And that’s what led to the problem at the start of this. They both work in doxygen and give the result I expected, But in Github
Markdown the first didn’t have named hyperlinks. It wasn’t until I added the spaces and blank lines between the td and the text of the cell. that the
links worked. It took some experimenting to get it to work in both cases. At least I was able to in both, so we’ve got that going for us.
