Support for question.md file as alternative to question.html

[jonatanschroeder]

Support for a markdown-only version of question.html. Elements are still supported as usual, with HTML-like tags inside markdown itself. This only affects freeform questions (i.e., v3), legacy questions are not affected.

For backwards compatibility, if a question has both question.html and question.md files, the HTML file takes precedence. Also, errors reading question.html other than "file does not exist" still trigger an issue.

Pending:

• question in example course
• tests of new markdown lib function
• tests of question using question.md
• docs

[eliotwrobson]

This seems very useful! I have two tangentially related questions (not necessarily worth piggybacking with this but mainly curiosity):

• Is it difficult to have the question.html file have a custom name?
• Is renaming server files with custom names of similar technical difficulty? (See Allow renaming server.py files for questions #7155)

[jonatanschroeder]

This seems very useful! I have two tangentially related questions (not necessarily worth piggybacking with this but mainly curiosity):

• Is it difficult to have the question.html file have a custom name?
• Is renaming server files with custom names of similar technical difficulty? (See Allow renaming server.py files for questions #7155)

These would likely require some configuration that involves changes in database, schema, sync, etc. which would be considerably more work than what is listed in this PR. I don't think they would be hard per se, it's just that they are not as trivial.

[jonatanschroeder]

Problem: elements like pl-multiple-choice (and other elements with sub-tags) may cause issues related to formatting. Due to the way markdown/commonmark handle HTML tags, there needs to be a blank line between an opening HTML-like tag and its content if you want to format the content itself. However this will typically cause <p> tags to be added in some contexts. For example, this:

<pl-multiple-choice answers-name="mc">

<pl-answer correct="true"> `a` </pl-answer>

<pl-answer> `b` </pl-answer>

<pl-answer> **c** </pl-answer>

</pl-multiple-choice>

causes the pl-answer lines to include <p> tags which are not supported by pl-multiple-choice. However, using this:

<pl-multiple-choice answers-name="mc">
<pl-answer correct="true"> `a` </pl-answer>
<pl-answer> `b` </pl-answer>
<pl-answer> **c** </pl-answer>
</pl-multiple-choice>

will not render the markdown formatting.

[jonatanschroeder]

One option to at the same time provide support for constructs like the one above and to make these a bit closer to markdown-flavoured is to use directives. So something like:

::: pl-multiple-choice {answers-name="mc"}
:pl-answer[`a`]{correct="true"}
:pl-answer[`b`]
:pl-answer[**c**]
:::

this would also simplify how elements like pl-question-panel work:

::: pl-question-panel
Question text *with markdown*
:::

This could be implemented with the remark-directive package. @nwalters512 and @mwest1066 thoughts?

[mwest1066]

Dang, this is exactly the problem I was worried about (nesting MD inside HTML inside MD). The comment below Example 109 indicates that some MD implementations allow a markdown="1" attribute to control this. For example, python-markdown has support for this. I couldn't figure out whether micromark supports this, although do see micromark's extension mechanisms.

I'm not super excited by directives. I'm worried that this is a pretty niche syntax that won't be well-supported by editors and other MD processors. I'd want to know a lot more about this before jumping in to such a substantial syntax change.

I wonder whether we'd be better off sticking with HTML but devoting more effort to improved editor support, such as WYSIWYG in-browser editors, VSCode plugins, etc. If the MD support that we want is small (do we want things beyond bold/italic/code?) then we could also consider implementing this ourselves directly on the HTML, like we do with latex where we treat $-pairs specially in HTML.

[jonatanschroeder]

Just adding these as notes. Support for markdown directives:

• remark/rehype: https://www.npmjs.com/package/remark-directive
• micromark: https://www.npmjs.com/package/micromark-extension-directive
• markdown-it: https://www.npmjs.com/package/markdown-it-directive
• VSCode: uses markdown-it, so can be extended to use it: https://code.visualstudio.com/api/extension-guides/markdown-extension

Support for markdown=1:

• python-markdown: https://python-markdown.github.io/extensions/md_in_html/

[firasm]

So would the idea be for PL to automagically insert markdown=1 into every HTML open tag for all question.md files?

That doesn't sound TOO bad - right?

P.S. FWIW, I'm a fan of directives, but I agree it's relatively early in their support/adoption and would be painful if it was changed. That said, question.md files are a new thing so maybe it's not the end of the world if things changed?

The nice thing is that as @jonatanschroeder pointed out with markdown-it and the newer markdown-it-py there are options.

[jonatanschroeder]

So would the idea be for PL to automagically insert markdown=1 into every HTML open tag for all question.md files?

Unlikely. What I personally find a better approach is that the markdown pre-processing done in lib/markdown.js would be changed to cause this behaviour without the need for markdown=1. That said, this needs to be thought carefully.

[github-actions]

All images

Image	Platform	Old Size	New Size	Change
prairielearn/executor:41642015feb825f3568c2e08e6c4758fb9367d9a	null	1619.17 MB	1619.18 MB	0.00%
prairielearn/prairielearn:41642015feb825f3568c2e08e6c4758fb9367d9a	linux/amd64	1619.17 MB	1619.18 MB	0.00%

[jonatanschroeder]

Closing as the current approach is unlikely to get track.