Answers are not formatted correctly

[lfdebrux]

Answers (code blocks within details sections) are not currently being formatted correctly; the contents of the details elements are being treated as normal HTML rather than Markdown or <pre>-formatted code.

See for example the answer for Task 4 in Lesson 2:

This is especially a problem for long answers, which may have linebreaks that are not being rendered by the Markdown parser.

I think I've traced the issue to a change in the tech docs gem Markdown engine, Redcarpet. There is an open issue describing a similar problem vmg/redcarpet#715, and we can see the change in commit vmg/redcarpet@5412f7e which was released in Redcarpet v3.4.0. The problem is that the current version of Redcarpet doesn't allow Markdown within HTML blocks [1]; I'm not sure whether this is by design or not (note that this is different to what the CommonMark spec expects [2]).

I think we have four (potentially non-exclusive) options to workaround/fix this issue:

• Rewrite answers to use HTML instead of Markdown code blocks
• Downgrade redcarpet to to a version pre 3.4.0
• Get Redcarpet to support Markdown within HTML blocks
• Get tech-docs-gem to support a different Markdown engine