rossbar
commented
3 years ago The consensus from the community meeting is using notebooks interactively is the highest priority use-case, so features that don't work with Jupyter interfaces (binder, jupyter notebook, jupyterlab, etc.) should not be used. Therefore - no extended MyST syntax in these notebooks! Closing the issue for now, though we should continue to monitor for support of extended MyST syntax in Jupyter.
The
myst-nbextension is used to provide support for the text-based notebook format. It also supports the MyST markdown flavor which adds additional functionality beyond what is available from commonmark markdown. One of the main features is support for sphinx roles and directives. This is a very nice feature, especially for integrating with other documentation - for example, you can use intersphinx to create cross-project references (e.g. between the notebooks and the main networkx docs).However, the problem that arises from using extended MyST syntax is that it is not supported in jupyter notebook itself. In other words, the roles and directives only work for
.htmland.pdfoutputs. For users running tutorials either with a localjupyter notebookinstance or on some cloud service like binder, the extended syntax will not render properly. To illustrate, I've created #31 which sets up intersphinx and uses it to reference a module in the main networkx documentation. If you view the static site in the build artifact, the link renders just fine. However, if you instead view things in Jupyter notebook (e.g.juypter notebook content/generators/geometric.md), the link will not be rendered.So the question is: do we use the full MyST syntax now, reap the nice benefits for the generated site and deal with having some warts when the tutorials are opened in
jupyter notebook, or do we limit ourselves to commonmark markdown so that all markdown elements render correctly in both html and notebook? I tend to lean towards the former, which will help integrate the notebooks content w/ the main documentation & especially since some of the things we hope to do with this repo (e.g. explanations of algorithms/graph concepts) would benefit greatly from extended support for math markup, e.g. proofs, theorems, lemma, etc..FWIW it seems there is interest in adding support for MyST to Jupyter itself (xref jupyterlab/jupyterlab#272, jupyter discussion forum post, executablebooks/meta#184, executablebooks/jupyter-book#1094, executablebooks/MyST-NB#210), but I wasn't able to find any info on a potential timeline for adoption.