Fragments – Previewing Richly Formatted Jupyter Book Style Content Authored Using MyST-md

Of the many flavours of markdown out there that can be used to author executable documents (Rmd, jupytext-md, and variants thereof, MyST-md), I find myself increasingly making use of MyST-md and Jupyter Book with various plugins to render the content to HTML (I haven’t tried rendering to other formats such as PDF, docx, or various ebook formats yet).

One of the major blockers to wider adoption that I’d expect “colleagues” to express is that raw markdown is too hard to write in and there’s no easy preview, let alone WYSIWYG, views.

But that appears to be changing, with several demos and proofs of concept around MyST-flavoured authoring now in play. It’ll be interesting to see whether this crop of tools provides enough of a basis for folk to start exploring MyST, and maybe driving some competition that will encourage further adoption and development.

So, what’s possible today? Let’s look at four possibilities: JupyterLab-MyST extension, Iridium notebooks, the Curvenote editor and the VS Code myst-vs-code extension.

Jupyterlab-MyST Extension

Perhaps most interestingly, a proof-of-concept JupyterLab extension, very much under development, in the form of jupyterlab-myst (Binder demo available, although the long build time and the fast rate of updates to the repo means you might well have to wait for a build to complete!).

The extension provides rendered views of an increasing amount of MyST native enhanced markdown features (I’m not sure if it will extend to rendering elements provided by plugins?), with markdown entered as normal in the edit view of a markdown cell.

I’m not sure if the extension works (yet?) in the pure-browser JupyterLite eenvironment?

One thing I’d quite like to see is the ability to use a cell tag to configure a markdown as a special content block rather than have to use a labeled code fenced block.

Some more examples of the jupyterlab-myst extension in action, at least as it stands today, including tables and footnotes (which are currently rendered at the bottom of a cell, and numbered relative just to the cell?):

I also note that nested admonitions work, term definitions almost work, and Sphinx function docs style rendering still needs work:

In Jupyter Book land, there are quite a few extensions that add further richness to content rendered via Jupyter Book, including dropdowns/sphinx-togglebutton, sphinx-panels, sphinx-tabs, proofs, exercises and so on. It’s not immediately clear to me whether there is an obvious path for incorporating those rendering extensions in the views that jupyterlab-myst can render, or whether the Sphinx extensions and the JupyerLab extension could share some of the same templates and styling? (I would hope they could share some of it at least…)

This all makes me wonder how easy it is for the end-user to define their own special content block tags and styles. If a really simple recipe could be found for supporting this sort of end-user development in the Jupyter Book / MysT context, as well as the jupyterlab-myst extension, it would go a long way towards making JupyterLab / RetroLab more palatable to me. For example, would a “custom block proxy” be possible where you define the code fenced block label and provide a template for how to render the content within the block?)

See also: A Personal Take on Customising Jupyter Via End-User Innovation

Irydium

The irydium project is a web-native browser based notebook offering MyST based authoring, in-browser Python code execution via Pyodide, and interactive graphical output via plotly charts. Javascript flavoured coding is also available using Observable Plot, which I think sits on top of d3.js.

The Irydium browser provides a split window display, with a MyST markdown text editor on the left and a previewer on the right. The two windows appear not to be locked – each scrolls independently of the other. As you type in the editor, thre previewer tries to display a live preview, although s the notebook gets longer the previwer gets slower and slower…

Basic admonitions are supported, although the {admonition} block which lets you set the block title, isn’t; nested blocks don’t seem to work, nor do the :class: attributes; the dropdown block does not appear to be supported (yet?) either.

Python and Javascript code cells are supported. Pyhton code execution is provided via a WASM Python environment provided by default. It doesnlt look like you can print Hello World? But you can (somehow?) pass state to a plotly Javascript widget.

Tables and tabbed content don’t appear to work (yet?) but panels do:

Maths notation / equations don;t appear to work (do we need to install a js package?) nor do footnotes:

Perhaps the biggest bigbear for me is that you need to log in to save the notebook. It would be nice to be able to:

• save and load named notebooks to browser storage, or to disk via the filesystem API;
• export / load myst-md files to / from the desktop.

Curvenote Editor

Compared to the side-by-side “source and preview” approach offered by Iridium, the Curvenote editor is a WYSIWYG web-based editor (open source, demo) that fronts the Curvenote publishing, collaboration and reuse platform.

Basic Markdown elements (headers, emphasis, lists, etc.) are entered as raw markdown, and code cells are triggered by entering three back ticks. Other custom blocks are created via a slash command that indexes into a drop down list:

Tables are created via a /table command:

Additional rows / columns can be addded via a pop-up toolbar, or slash commands inside the table:

Footnotes and and equations are also entered from slash commands.

Slash command can be invoked inline, for example, when adding a footnote:

The document source is available as MyST-md (somehow???); blocks, equations and tables are all generated as expected, but not the footnote (which appears as a popu-up in the HTML, rather than appearing inline at the foot of the page), unless I’m doing it wrong.

For example, for this WYSIWYG view:

The following MyST-md is generated:

I’d prefer it if the table were not enclosed in a block.

For folk who like WYSIWYG editors, and who are comfortable with / commands, for example, as used in the WordPress Gutenberg block editor, the editor makes it easy to flip between edit and rendered views of styled elements, with the syntactic boilerplate provided for you. Styled blocks are invoked inline from slash commands and selected from a filtered list.

This approach balances WYSIWYG and “toolbar button” applied styling or raised wizards, and appear to be “a thing” in many (developer driven?) environments. (Keyboard shortcuts are also supported, but I’m not sure how deep they go? Eg can you raise the table editor or a note block from a keyboard shortcut?) But they go against my personal preferences (I really dislike the WordPress editor, for example: I’d rather just write in markdown.)

VS Code myst-vs-code Extension

The executablebooks/myst-vs-code extension provides rich preview rendering of MyST markdown documents. The rich preview view is rendered in a separate panel to the edited document.

For example, we can preview various flavours of special content block / admonition block:

We can also define footnotes, which are rendered at the botton of the preview, and create tables from markdown table syntax.

Equations / maths notation didn’t seem to render for me though because I couldn’t seem to find a way to enable additional extensions?

I also wonder how additional extensions are added, and what these have in common with the Sphin extensions? Eg how easy would it be to add support for the exercise, panel or proof extensions?

The previewer doesn’t work if the shd101wyy/markdown-preview-enhanced is enabled, though (my preferred VS Code markdown extension; there is also a slight variation in the sytax preferred by markdown-preview-enhanced compared to MyST, as noted in this related issue).

See also: VS Code as an Integrated, Extensible Authoring Environment for Rich Media Asset Creation.