Audit of Features missing in JupyterBook

[rowanc1]

Although mystmd and JupyterBook/sphinx are targeted at slightly different use-cases, there is overlap in creating websites (see background). Below is a list of missing features/directives/roles/ui that are not yet implemented in mystmd, we hope to have parity at the rendering level first, then move on to extensibility (see #181 as a major step).

We will try to keep this updated as we audit more jupyterbooks.

Directives

• [x] prf https://github.com/executablebooks/mystjs/pull/384
• [x] tasks #187
• [x] grids
• [x] cards (header/footer)
• [x] dropdown
• [x] tab-set
• [x] sphinx proof #384
• [x] sphinx exercise #399
• [x] glossary / terms #411
• [x] literalinclude https://github.com/orgs/executablebooks/discussions/1026, https://github.com/executablebooks/jupyterlab-myst/issues/189 #610
• [x] table #593
• [x] raw #939
• [x] epigraph #961
• [x] margin #516
• [x] sidebar #1012
• [x] topic #1132
• [x] div
• [x] index
• [ ] bibliography
• [x] only #613
• [ ] nb-exec-table
• [ ] grid-item
• [ ] grid-item-card
• [x] csv-table #893 #1030
• [ ] #1338
• [ ] toggle (show option)
• [ ] button-ref
• [ ] footbibliography
• [ ] figure-md
• [ ] tab
• [ ] panels
• [ ] contents
• [ ] field lists
• [ ] rubric
• [ ] card-carousel
• [ ] eval-rst
• [ ] example
• [ ] glue, glue:, glue:figure, glue:math
• [ ] raw-cell

Roles

• [x] doc #387
• [x] term
• [x] download #440
• [ ] bdg-primary
• [x] cite:ps, cite:ts #82
• [ ] fa
• [ ] py:class
• [ ] glue:, glue:text
• [ ] guilabel

Config

• [ ] edit_page_button, repository button, issues_button
• [ ] ... audit the _config.yml
• [x] read the relevant parts of the _config.yml for sphinx

Extensibility

See #181 as a roadmap.

• [ ] transforms turned on (e.g. dollarmath, etc.)
• [ ] directives / roles #181

Execution

• [x] running code execution for a notebook #550
• [ ] Linking artifacts from a notebook (glue) - we are supporting this using ids/imports (see docs)

Improvements

• [x] #284
• [x] hide code or output #407
• [x] https://github.com/executablebooks/mystmd/issues/1108
• [x] admonition: classes
• [x] admonition: dropdown class
• [x] intersphinx

UI

• [x] TOC - collapse https://github.com/executablebooks/myst-theme/pull/254
• [ ] logo more like JB
• [ ] toc footer
• [ ] #1920
• [ ] https://github.com/jupyter-book/myst-theme/issues/509
• [x] search #100
• [x] favicon #925
• [ ] https://github.com/jupyter-book/myst-theme/issues/510
• [ ] internationalization #166

URL:

• [x] Collapsing things down to a project/slug isn't how JB works #670

Export

• [x] static html #188
• [ ] https://github.com/jupyter-book/mystmd/issues/1921

[jan-david-fischbach]

@rowanc1 To implement a feature on this list we need to simultaneously consider LaTeX and the Web output, correct? How could we go about sidebar/margin content? Using \minipage or similar does not really float my boat. At the moment I would be in favor of adding the sidebar content to the appendix, or to add it below the current paragraph as a content box. What do you think?

[rowanc1]

It would certainly be appreciated to consider both html, latex and other exports, however, we can take contributions that get us there in a few iterations. The default falls back to rendering the child content, so it is just inline in the document. I think this might depend on what template you use and as you suggest, there isn't really a good default in latex!

If you are interested in implementing one of these features, can you open a specific issue on it? We can help give some guidance on where to look and how to get started!!

[jan-david-fischbach]

Maybe I'll find some time to work on the sidebar soon. Trying to come up with a workaround I noticed that html tags are not left unchanged:

The myst-spec doesn't seem to say anything on how raw html is to be treated. The cheatsheet (which seems to be jb-flavoured myst) seems to indicate that html is interpreted as is.

Edit: It seems that one can set some allowDangerousHtml flag somewhere. I just don't know where yet

[rowanc1]

I have opened and linked #516 with a few pointers to start, just ping me if you start working on it and get stuck and I can try to help out fast!

There is an outstanding bug for the HTML here:

• #418

It works fine when the round-trip is HTML (e.g. using the underlying js libraries), but our renderer is react, so we actually need the AST of the HTML correct, which is currently incorrect and not nested properly. For example, this AST of bold is [html, text, html] rather than [html > text] or converted to [strong > text] in this simple case. This is still going to be a bit of work to sort through.

[jan-david-fischbach]

Even with the "wrong" AST[^1] one seems to produce correct html with the allowDangerousHtml option:

import { u } from 'unist-builder';
import { mystToHtml } from 'myst-to-html';

let ast = u('root', [u('html', '<b>'), u('text', 'test'), u('html', '</b>')]);

const skewed_html = mystToHtml(ast);
console.log(skewed_html); // test

const html = mystToHtml(ast, {'hast': {'allowDangerousHtml': true}, 'stringifyHtml': {'allowDangerousHtml': true}});
console.log(html); // <b>test</b>

[^1]: The correct handling of html doesn't seem to be firmly defined: Does it all go into one html node, or using children for the content. How is markdown syntax inside html handeled etc.

[rowanc1]

Yes, it will work for explicit HTML outputs which is string concatenation! However most of the tools are built on React, which operates on the AST and will try to create <b> as HTML, then 'test' text, then </b>. Which will end up with <b></b>test as the first node closes by default and the closing node isn't rendered. I think it is a bit worse actually as it looks like there is an extra paragraph, <b>test</b> turns into:

Not great, and something to fix up soon (#418)!