search

executablebooks / myst

Myst - Markedly Structured Text
3 stars 2 forks source link

proposal: deprecate indented code blocks #16

Open akhmerov opened 4 years ago

akhmerov commented 4 years ago

While these are in the markdown spec, AFAIK fenced ones are much more popular. At the same time having those makes myst the second markup format to recommend indenting by 3 spaces ;)

Perhaps there could be a parser setting that controls whether these are parsed as code?

choldgraf commented 4 years ago

I raised a similar issue about allowing embedded HTML. In that thread, we concluded that we probably shouldn't split from the CommonMark specification. One of the main benefits / goals of MyST is that it is a strict superset of CommonMark (partially, so that any notebook already in existence will be a valid MyST document).

What if we started raising some kinds of warnings for this behavior? We can choose a subset of the markdown features that we don't consider to be best practice, and flag it when people use it?

akhmerov commented 4 years ago

A warning sounds like a good idea. I imagine, as MyST evolves, it might be useful to remove some syntax, and this is one way to start the process.

Rethinking the motivation for my question: directives aren't a part of a commonmark spec. Therefore saying that an indented code block may not occur within a directive wouldn't prevent MyST from being an extension of the spec.

choldgraf commented 4 years ago

Ah - so you are proposing "turning off" this indentation rule only inside the code fences? That might be a different story. @chrisjsewell what do you think?

I foresee people indenting their code fences with 4 spaces and being confused far more often than people legitimately want to embed a "raw" block within code fences with 4 whitespaces.

akhmerov commented 4 years ago

Ah - so you are proposing "turning off" this indentation rule only inside the code fences?

More specifically only inside MyST directives. To be commonmark compliant, anything that happens inside fenced code should stay uninterpreted.