✨ NEW: Use external markdown-it plugins

[chrisjsewell]

Replaced the (very adhoc) local markdown-it plugin for directives, with https://github.com/executablebooks/markdown-it-docutils, and in general it works 🎉 ! (some notes and todos below)

TODOS:

• markdown-it-docutils has not yet implemented code/code-block/code-cell directives; once that is done there will be > parity with the plugin it is replacing
  • I noted that, incorrectly, {code-block} does not get parsed as a directive, which needs to be fixed, i.e. the regex needs to include -
• The required markdown-it plugins should be added (i.e. front-matter and footnote)
• The additional myst extensions should be added (dollarmath, amsmath, deflist, ...), and turned on/off via a setting
• Currently I have just copy/pasted markdown-it-docutils/dist/css/style.min.css to ./styles.css, but it would be good to have this updated automatically
• For some reason the admonition icons are not showing correctly, I also noted this when looking at https://executablebooks.github.io/markdown-it-docutils/ on my mobile (ios)
  • Note this is not the case for Furo itself (where the icons come from), so I must be missing something from there 🤷
• when you place a cursor, or highlight some text, in the source text, you can see above that the line it is on is also indicated in the preview. However, for admonitions their styling appears to obstruct it.
  • Note that it does show up for "indented" components like lists;
    
  • This also highlights the importance of correctly setting Token.map for all the (block) nodes
• Currently the CSS (taken from https://github.com/pradyunsg/furo, see https://github.com/executablebooks/markdown-it-docutils/blob/main/src/style/_variables.scss) uses @media (prefers-color-scheme: dark) to change between light and dark themes. This doesn't necessarily play well with the VS Code themes, so should think about either (a) if this is the best approach in the first place and/or (b) if we should override some of these variables.

@rowanc1 it would be great if you give this a try (the dev instructions are in the README); it would be good for you to understand this use case for the markdown-it plugins, and maybe even get some idea for curvenote 😄

also cc @pradyunsg (as mentioned I borrowed some of your sass from Furo 😄)

[rowanc1]

Just seeing this in the css -- https://caniuse.com/css-masks is not in chrome/webkit which this uses.

Mine currently look like this in Chrome here: https://executablebooks.github.io/markdown-it-docutils/:

(changed the mask property on the second one...)

[chrisjsewell]

Ah cheers, that could be it then 👍

[chrisjsewell]

Ah so furo uses https://github.com/postcss/autoprefixer (via gulp) during the css compliation, which auto-adds vendor prefixes (which is why I did not find e.g. -webkit-mask-image in the actual sass)

[chrisjsewell]

After update to markdown-it-docutils v0.0.10:

[adam-grant-hendry]

Sorry to dig up this old PR. It doesn't look like {toctree} directives are supported or properly rendered.