Enable MyST for use in info-view metadata section.

[wxtim]

Also replaces markdown-it with the more powerful package MyST.

After offline discussion @oliver-sanders and I decided to try MyST because

• It has both Python and JS interfaces, so we can allow users to both build docs with Sphinx and display them in the GUI.
• It is a superset of markdown, so at a basic level users can use MD.
• It has many of the features of RST available, so more sophisticated documents can be written.

Branch-specific checks

• Mutation.Vue
• FormGenerator.Vue
• Input.Vue
• MyST security escaping documentation read.

Security

I can't find a vast amount of info:

The default for CommonMark standard is to pass everything through (or at least that's what CommonMark.js does)

But this doesn't seem to be implemented by MyST.js, whose own rather limited docs suggest that only <sub>, <super> and <abbr> will do anything. Testing this out seems to suggest that these aren't parsed correctly!

> myst.render('<p>Hi</p>')
''
> myst.render('<sub>Hi</sub>')
'<p>Hi</p>'
> myst.render('<style>.foo {color: #f00}</style>')
''
> myst.render('<script>console.log("copy rm -fr /* and run it in your terminal")</script>')
''
> myst.render('<center>Hi</center>')
''
> myst.render('<p>Hi</p>')
''

Check List

• I have read CONTRIBUTING.md and added my name as a Code Contributor.
• Contains logically grouped changes (else tidy your branch by rebase).
• Does not contain off-topic changes (use other PRs for other changes).
• Applied any dependency changes to both setup.cfg (and conda-environment.yml if present).
• Tests are included (or explain why tests are not needed).
• Changelog entry included if this is a change that can affect users
• Cylc-Doc pull request opened if required at cylc/cylc-doc/pull/XXXX.
• If this is a bug fix, PR should be raised against the relevant ?.?.x branch.

[wxtim]

@oliver-sanders - I'm a little concerned that MySTjs is quite primitive atm - See the list of features not available in mystjs at https://www.npmjs.com/package/mystjs#mystjs-features.

I'm also concerned that we may need to supply our own CSS to make it render well:

The code isn't well rendered, and the admonition and the maths aren't rendered at all. Inspection suggests that they have the correct classes for styling, but that there isn't any inline: Inserting some CSS into the markdown made the tip box look like a tip box, but I'm not sure that we should be responsible for that.

[oliver-sanders]

@oliver-sanders - I'm a little concerned that MySTjs is quite primitive atm

Quoting from the link, these are the missing features:

Not yet complete:

div
proof
margin
sidebar
colon fence
Citations
Bibliography
Epigraph
Glosary
Terms
Tabs
Panels
CSV Tables
Multi-document

These are all either HTML features or ReStructuredText features.

MySt would appear to be feature complete for the common-mark specification.

So I think this is pretty good.

I'm also concerned that we may need to supply our own CSS to make it render well:

Their examples render very nicely, see the sandbox - https://mystmd.org/sandbox

From a quick search of the repo I found this CSS. You may need to link it into your HTML if using the JS library standalone:

https://github.com/jupyter-book/mystmd/blob/68c93b9a07014e01eac4d721dfd3b5f74d174258/packages/myst-parser/myst.css

[oliver-sanders]

@wxtim, have you pulled through the MyST CSS in this PR?

[wxtim]

@wxtim, have you pulled through the MyST CSS in this PR?

Not yet - drafting until I've worked it out.

[oliver-sanders]

(unsubscribing)

[wxtim]

Manual Test, showing what is possible:

The Workflow Definition

[scheduling]
    cycling mode = integer
    [[graph]]
        R1 = foo

[runtime]
    [[foo]]
        script = while true; do sleep 30; done
        [[[meta]]]
            title = "My Title"
            description = """
                # Every Single

                some text

                ## Heading

                some text

                ### Level

                some text

                #### Possible

                some text

                ##### No

                some text

                ###### Rêally

                > A moose bit my sister once.

                ---

                ## New section

                % This is a comment.

                [Great Auk - link example](https://en.wikipedia.org/wiki/Great_Auk)

                ![Great Auk](https://upload.wikimedia.org/wikipedia/commons/4/4e/Great_Auk_%28Pinguinis_impennis%29_specimen%2C_Kelvingrove%2C_Glasgow_-_geograph.org.uk_-_1108249.jpg)

                ## Lists

                1. First item
                2. Second item
                  * Yellow Submarine

                ## Admonitions

                :::{note}
                B flat
                :::

                :::{warning}
                Live without warning.
                :::

                :::{tip}
                My hobby room
                :::

                :::{danger}
                Mouse
                :::

                :::{caution}
                Horses
                :::

                :::{admonition} My Admonition
                :class: customadmonition
                This is a custom admonition.
                :::


                ## Maths

                This math is a role, {math}`e=mc^2`, while this math is wrapped in dollar signs, $Ax=b$.


                ## Table

                :::{list-table}
                :header-rows: 1
                * - Header 1
                  - Header 2
                  - Header 3
                * - Row 1
                  - Row 1
                  - Row 1
                * - Row 2
                  - Row 2
                  - Row 2

"""
Another Metadata Section = """
            :::{note}
            This is a note admonition.
            :::

            """

How about some code blocks = """

            :::{code-block} python

            # Python
            def foo():
                return "bar"
            :::

            :::{code-block} bash
            #!/bin/bash
            # Bash
            echo "Hello, World!"
            :::

"""

The Output

Note

I've note made this an explicit test in the test battery because that woudl be testing the dependency.

[wxtim]

@oliver-sanders : Ready for review

[MetRonnie]

Could you add some example markdown that makes use of this to src\services\mock\json\infoView.json

[oliver-sanders]

Looks like the myst-theme package provides CSS: https://github.com/jupyter-book/myst-theme/tree/main/styles

Can we just import this from there? We can always apply additional modifications if needed.

[wxtim]

I'm not sure that will work - a quick look at that library suggests that it doesn't really contain things like .admonition which are required.

[oliver-sanders]

Yet they seem to have good support for admonitions on their website?

https://jupyter-book.github.io/myst-theme/?path=/docs/components-admonitions--docs

[wxtim]

Jupyter-book is using myst-to-react, which looks like it's different output to myst-to-html. I can see if I can do that, but it sounds a bit wierd.

[wxtim]

I spent quite a while trying to address this as well as trying to get the maths parsing working - these threads seemed to hint at solutions, but I was unable to- get them working:

• mathPlugin adds .html attribute to node, but seems to be ignored in mystToHast jupyter-book/mystmd#859
• How to use myst-parser in browser to generate html from myst markdown string? jupyter-book/mystmd#824

There was a suggestion that css could be included like this:

  .use(rehypeDocument, {
    css: ['myst.css', 'https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css'],
    js: ["https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.js", "https://cdn.jsdelivr.net/npm/[email protected]/dist/contrib/auto-render.min.js"],
    script: `document.addEventListener("DOMContentLoaded", (event) => {
        renderMathInElement(document.body, {
            delimiters: [{
                    left: "$$",
                    right: "$$",
                    display: true
                },
                {
                    left: "$",
                    right: "$",
                    display: false
                }
            ]
        });
    });`
  })

But I haven't been able to make that work either.

[MetRonnie]

(Needs deconflicting, and this:)

Could you add some example markdown that makes use of this to src\services\mock\json\infoView.json

[MetRonnie]

We could look at more carefully incorporating the old styling into the new, as it was chosen to ensure the limited Markdown we already had fits with Vuetify