Open lfdebrux opened 3 years ago
I think quite a few markdown parsers stop parsing markdown within HTML, or only parse it in certain circumstances.
The Commonmark spec seems to suggest that whether or not markdown is parsed can also be affected by the presence of blank new lines before the markdown…
We could consider authoring the entire table in markdown, but given the size of the table that might introduce more problems than it solves.
In the large
<table>
element ofsrc/styles/page-template/index.md.njk
, Markdown syntax such as links ([link text](href)
) and code spans (`code`
) don't work.Cause
I'm not sure why yet; it may be a limitation of the parser or of the spec.
Consequences
This means we have to include the HTML markup in this section, which is different behaviour to every other part of the document. This is easy to forget to do. Tech writers and developers need to be aware of this when updating this table, or reviewing changes to it.
Impact of debt
Medium.
There is a high likelihood of people forgetting to use the correct markup, but the severity of such a mistake is low. The worst possible outcome is a user seeing text that should be a link but is instead is text in square brackets followed by a link in parentheses. The likelihood of this outcome can be further reduced by careful code review, and documenting the issue in the file.
Effort to pay down
Medium.
It may be possible to work around the however by using Nunjucks constructs, or by changing the Markdown parser, but this would require some exploration.
Overall rating
Low