Consider using pandoc markdown for "div"s and RMarkdown for code cells in Jupytext markdown

[choldgraf]

In using Jupytext, I've found that I'd love to have a combination of two features from two different markup languages supported by jupytext:

Pandoc div fences for markdown cells

I often want to tag-up my markdown with metadata that is cell-specific, which means that I need to be able to separate out my markdown chunks into multiple cells. Right now in Jupytext, the way to do this is to write <!-- md --> and <!-- endmd -->. This isn't bad, but it is a bit cumbersome. I find it much more streamlined to use the Pandoc syntax for divs, such as:

:::md
:::

as opposed to

<!-- #md -->
<!-- #endmd -->

This could be extended to other types as well, e.g.:

:::raw
:::

What do you think about supporting syntax such as this for Jupytext markdown?

RMarkdown code blocks in markdown cells

Another feature I love about RMarkdown is the ability to distinguish "regular" code blocks (using python) from "runnable" code blocks (using {python}). This could be a nice way to separate out the same behavior in Jupytext markdown.

I'm curious what others think about incorporating these into the base flavor of Jupytext md (In addition to manually specifying with comments).

[mwouts]

Hello @choldgraf , I agree that pandoc div are easier to type, and nicer to read in a text editor. But... they don't look nice yet in GitHub or in VS code... that was the reason why we did'nt took them. That said, sure, why not allowing them in addition to the other cell markers, as you suggest? I'll think about that.

The same remark holds for the RMarkdown code blocks: I don't think that ```{python} blocks are well rendered on GitHub... But I agree with you that having a simple way to distinguish between executable and non-executable cells is necessary.

[choldgraf]

Yeah, I agree with you on both points. I think it's a tricky situation. On the one hand, it simplifies things if the interfaces people are familiar with will understand the syntax that is used. On the other hand, embedding lots of comment blocks in the markdown is also not the most visually-appealing, even if the comments are properly colored.

Perhaps another option would be to allow for ::: fences in the RMarkdown format conversion? That might introduce the problem of it not strictly adhering to RMarkdown though...

[mwouts]

Hello @choldgraf , I see that Markdown allows both ``` and ~~~ to define code sections (that seems to be compatible with GitHub, VS Code, PyCharm at least). What would you think of using ~~~python for the code parts that you don't want to be execute in Jupyter?

If you like the idea, I'll add a test (to ensure that Jupytext leaves ~~~python unparsed...), and a mention in the documentation, since that's probably a good alternative to the .noeval flag...

[choldgraf]

I have been thinking it over, and almost wonder if this shouldn't be handled at the tech level, but instead at the documentation level. Rather than building new features into the vanilla markdown, why not just tell users that they should use RMarkdown if they need the ability to distinguish "runnable" from "non-runnable" code blocks? (this should just be a matter of adding the {} to the code fences, right?)

[mwouts]

It has been some time since we last discussed this...

• Indeed people can use Rmd if they want to distinguish between runnable and non-runnable code cells
• I have added the ~~~python trick to the documentation to make non-runnable code cells in the markdown format
• I am not sure I would invite non R users to use the Rmd format, because the code cell metadata have to be coded in R
• More generally, I have the intuition that these kind of questions will be adressed with the myst format (A book publishing project interested in extending jupytext code  #447)... do you mind if we continue the conversation there?

[choldgraf]

Yep, that sounds good to me.