search

alphagov / govuk-design-system

One place for service teams to find styles, components and patterns for designing government services.
https://www.gov.uk/design-system
MIT License
509 stars 231 forks source link

Markdown formatting does not work in table in `src/styles/page-template/index.md.njk` #1722

Open lfdebrux opened 3 years ago

lfdebrux commented 3 years ago

In the large <table> element of src/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

36degrees commented 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.