Markdown Fenced code block with info vs. code-block directive

[jenisys]

The MyST documentation describes the {code-block} $LANGUAGE directive/idiom and uses it in many places. Common Markdown already supports a simpler construct Fenced code block with info string that does the same thing (as long as no code-block parameters/attributes are needed).

EXAMPLE: Using code-block directive in MyST / Markdown

```{code-block} python
def func():
     pass
```

EXAMPLE: Using Markdown Fenced Code Block with info string (here: info=python)

```python
def func():
     pass
```

DESIRED SOLUTION: I would suggest that the Markdown Fenced code block with info is also documented as an alternative (that is more natural to Markdown users). Maybe, it should also be contained in the examples section of the documentation.

ASSUMPTION: I assume that Markdown Fenced code block with info is properly handled (in Sphinx) by leading to the corresponding code-block directive/construct.

SEE ALSO:

• CommonMark: Fenced code block with info string, example

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[chrisjsewell]

Heya, yep the Markdown fence is just handled as a special case of the code-block directive (i.e. with no options allowed).

Happy to receive PRs to improve the documentation 😄

[nathanrpage97]

@chrisjsewell could there be an extension to allow markdown-fence to support options? It would be nice to get syntax highlighting in editors, while also being able to set :linenos: and other features

[mgielda]

I think that would be an awesome idea! Just read that bit of the spec and it struck me that a block starting with ```python lineno-start: 10 (or similar) is valid CommonMark, the spec says you're free to do what you want with the stuff that comes after the first word which is treated as the language definition.

From what I've seen most renderers just ignore the arguments after the first word. This would make code blocks render nicely also outside MyST. The ones with {code-block} python don't, which is a pity given that 80% of the directives I use in a document are usually code-blocks.

So essentially something like:

```python lineno-start:2 
def sth():
    pass
```

Which in GitHub renders as

def sth():
    pass

Would that be a welcome addition? (of course the syntax could also be x=y or :x:y etc., x:y was just an example)

[chrisjsewell]

Hey @mgielda just to note, I'm very much a fan of djot, and would like to merge more with that, to that end, block attributes would be the answer here; https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/master/doc/syntax.html#block-attributes

[mgielda]

Interesting - let's see:

{lineno-start=2}

def sth():
    pass

Sadly, this extra input renders on GH but maybe for the better...

[mgielda]

Didn't know about djot BTW, thanks @chrisjsewell

I wish dj became the new md spec superseding commonmark rather than its own format, since there are slim chances everyone/everything starts supporting and knowing the new syntax (even if it's very similar to md).

But if - for out of spec functionality added to md - we can use dj's convention, why not.

Overall "md with superpowers" which I consider MyST to be is a nice niche to be in. Having md's standard code blocks with the ability to add Sphinx-ready arguments to them would fix a MAJOR headache for us. Essentially, we dropped rst altogether in dozens of projects we run in favor of MyST but the one downside is that e.g. GitHub can render rST code clocks but can't do MyST (since it's not aware that a non-standard md flavor is being used). So MyST md documents end up being full of uncoloured code blocks etc.

I think having the arguments display explicitly like in the example above is not horrible either. At least it's clear they are there.

[chrisjsewell]

thanks for the feedback @mgielda,

yeh exactly obviously it will be difficult to get everyone to suddenly drop markdown in favor of djot, but I think djot is the best shot for a truly "standardised markdown+". Plus its by the creator of Pandoc, so there is a lot of good thinking there as to the best syntaxes etc. For these reasons, I definitely want to nudge MyST in the direction of djot

[mgielda]

The feature we're talking about, the block arguments etc., is certainly in no way colliding with markdown in general, at least in everyday use. I can see how MyST adopting this kind of syntax could potentially push e.g. GH to support this at some point (as a "why not" kind of feature), which in turn would make md - in its practical form - more like djot.

[chrisjsewell]

FYI, @mgielda if you wanted to push this forward, the steps would be:

• Add a plugin to https://github.com/executablebooks/mdit-py-plugins, to implement https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/master/doc/syntax.html#block-attributes
  • This can use https://github.com/executablebooks/mdit-py-plugins/blob/master/mdit_py_plugins/attrs/parse.py
• Add an "attrs_block" item to the enable_extensions list here, that turns on the plugin
• Adapt the render method for fences, to utilise the extra attributes on the markdown-it token

[mgielda]

Thanks @chrisjsewell - am I to understand that if that were implemented, you would be sympathetic towards merging it?

(BTW I did not fully understand "Add a plugin to https://github.com/executablebooks/mdit-py-plugins, to implement https://github.com/executablebooks/mdit-py-plugins" - were the links supposed to be different? since now they are the same)

I will be honest that while I will not be the person to implement it, I can probably find someone internally to help out with this - assuming that there is a high likelihood this is going to land given a correct, non-intrusive implementation. I would very much appreciate the capability to use native code blocks.

[chrisjsewell]

you would be sympathetic towards merging it?

yep definitely 👍

were the links supposed to be different? since now they are the same

To implement https://htmlpreview.github.io/?https://github.com/jgm/djot/blob/master/doc/syntax.html#block-attributes

[chrisjsewell]

[mgielda]

Meaning you actually went and did it? That is awesome! Let me try this internally.

[chrisjsewell]

Meaning you actually went and did it? That is awesome! Let me try this internally.

I only went and bloody did it 😝 https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#block-attributes

[mgielda]

Could that also be made to work with md-native images, to give them rst "figure"-like capability? That would be so awesome!

One challenge is that rst has both image and figure; we use figure most of the time since we use numbered figures which make use of the caption. Not sure how to handle this exactly, perhaps we should open up a separate issue to discuss this? Was this idea ever floated around?

[chrisjsewell]

@mgielda did you see: https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#markdown-figures, i.e. to do

:::{figure-md}
:caption: A caption

![](image)
:::

(note, this was added before the "advent" of attributes, so maybe is a way to now "combine" them)

[rowanc1]

Would love to see an issue in the myst-spec repo!! Been thinking about this in the mystjs parser as well!

[chrisjsewell]

As is obligatory for me to now do 😆 a link to the relvant djot issue: https://github.com/jgm/djot/issues/31

[mgielda]

@chrisjsewell Ah, yeah, I forgot about that syntax, thanks for reminding me! I think an attributes solution could be more elegant, right?

:::{figure-md} name :caption: A caption

:::

[mgielda]

The overarching idea would be to try to get e.g. GitHub to support things like those attributes - I think converging to things understood by "standard" md parsers where possible (as understood by GH/GL etc) would make MyST a very very compelling option.