Links to sample md files do not work in read the docs

[mwouts]

I just subscribed to the Tracking Jupyter newletter by @psychemedia (Super interesting, thanks Tony for your work there, and for all the mentions of Jupytext!)... and I wanted to answer one question by Tony - He was wondering how the pandoc Markdown format compares to Jupytext's one.

The answer is in the demo folder, where the World population notebook is represented in each of the available formats.

But on this occasion, I also see that the link to the pandoc sample in our readthedocs documentation does not work - it goes to https://github.com/mwouts/jupytext/blob/master/demo/World population.pandoc instead of https://github.com/mwouts/jupytext/blob/master/demo/World population.pandoc.md, i.e. the .md extension is missing. @choldgraf, maybe you will know how to fix that? Thanks!

[choldgraf]

I think I figured this out, will add it to #257

[mwouts]

The link is working now! Thanks Chris.

[psychemedia]

Re: the diffs between Jupytext and pandoc .md: thanks for that demo folder. Just been having an explore via @choldgraf's Binder link in #257 and the diffs seem to be quite mechanical, e.g. pandoc's use of ::: {.cell .markdown} delimiters.

Are the differences in the use of apostrophes in the jupytext header metadata meaningful?

Also, I note a diff in the presence of the nbformat metadata?

[mwouts]

Are the differences in the use of apostrophes in the jupytext header metadata meaningful?

I think they are not. I mean, both headers are valid YAML. Probably the difference here comes from the way they are written. Jupytext's one is writen with pyyaml, while Pandoc's one is writen by pandoc itself.

Also, I note a diff in the presence of the nbformat metadata?

Pandoc preserves the nbformat information by including it in the notebook metadata (in the notebook itself it is at a different level). I have not seen the need for that yet in the other formats.

@psychemedia , you should expect a few more differences on

• markdown cells with metadata
• and markdown cells with two consecutive blank lines.

We discussed the two formats some time ago with @jgm on pandoc-discuss. Given the differences, I have chosen to implement the pandoc format by calling pandoc itself, cf. pandoc.py, after applying Jupytext's filters on the notebook and cell metadata (otherwise you would have seen a longer header). You could also have a look at #208, especially to the recent discussion with @ickc starting with this comment.

[ickc]

@psychemedia, note that markdown has a lot of different flavors and pandoc is one of them. (pandoc is both a program that converts between a ton of formats, and a markdown flavor, occasionally called Pandoc Favored Markdown.)

the ::: and {} you are seeing are the div marker and attribute markers respectively. The diff. you're seeing is the YAML header is because pandoc has its own YAML parser that is written in Haskell (in fact most of pandoc is written in Haskell.)

At the very least you could consider the diff you're seeing is just 2 different "flavors", 2 different ways a mapping between ipynb and md can be realized.