markdown: explicitly say whether GFM is supported

[ee7]

I believe that the website uses commonmarker (see here), which is the wrapper for libcmark-gfm. And therefore the website supports rendering a markdown file that uses GitHub Flavored Markdown features.

However, the Exercism Markdown spec does not state whether a Markdown file can use GFM features. We should state that explicitly, so that e.g. a track knows whether they can use a tables, task list items, or strikethroughs.

Configlet will soon learn to parse and render Markdown, but this will at least initially only support the CommonMark 0.30 spec (not GFM). If necessary, it should be straightforward for it to support GFM (by wrapping libcmark-gfm, rather than libcmark).

Somewhat related: GitHub is thinking about adding a new admonition syntax. See https://talk.commonmark.org/t/4173

But even if the GFM spec is changed, I would suggest that we keep the current admonition syntax:

All blocks are written using 4 tildes, in the form of:

~~~~exercism/note 
Content goes here 
 
You can include code: 
```ruby 
str = "Hello, World" 
``` 
~~~~ 

(Note: You may also use backticks or other levels of tildes in exceptional circumstances)

[ErikSchierboom]

FYI The additional rendering options that we support are footnotes and allowing unsafe HTML: https://github.com/gjtorikian/commonmarker#render-options

[ee7]

Thanks. Do we support tables and strikethrough too?

• website/app/commands/markdown/parse_doc.rb#L10
• website/test/commands/markdown/parse_test.rb#L70-L94
• website/test/commands/markdown/parse_test.rb#L144-L146

What's the rationale behind using UNSAFE? And how does it interact with tagfilter?

---

To others, links about footnotes:

• https://github.blog/changelog/2021-09-30-footnotes-now-supported-in-markdown-fields/
• https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#footnotes
• Footnotes aren't in the latest GFM spec (which also isn't 0.30 yet)
• https://talk.commonmark.org/t/footnotes-now-supported-by-githubs-web-interface/3983
• https://github.com/github/cmark-gfm/commit/59f723304ffc3b84f781431a320dffa2dea03fdd (GitHub Pages supported footnotes 3 years before github.com or gists)

[ErikSchierboom]

Do we support tables and strikethrough too?

Yes.

What's the rationale behind using UNSAFE? And how does it interact with tagfilter?

@iHiD?

[iHiD]

No idea. I guess we trust maintainers' code and allow them to do whatever?

[ErikSchierboom]

🤷

[ee7]

I'd probably lean towards:

• If there's no real reasonable basis for rendering unsafe HTML in markdown from Exercism track repos, stop doing that. This helps minimize the extent to which the security of the website is dependent on reviewers catching potentially subtle security issues, right? Or do we see legitimate uses for things like <iframe> and <script>?
• Regardless, we should have a markdownlint workflow in org-wide-files (tracked in https://github.com/exercism/org-wide-files/issues/214) eventually anyway.
• Then we can configure that workflow to produce an error for unsafe HTML. If we keep allowing it, perhaps that markdownlint error could be disabled on a repo-by-repo basis, with its configuration requiring @exercism/maintainers-admin approval.