Syntax documentation, myst-parser vs mystmd, and sphinx-myst --help

[72757373656c6c]

Question

I added colon_fence to myst_enable_extensions. In issue 493, Chris shows nesting directives, so a user could write:

• :::{note}

• ```{note}

• ~~~{note}

Is the tilde (~) officially documented? If so, where?

Question

If the main MyST-Parser documentation is https://myst-parser.readthedocs.io/, what is https://mystmd.org?

Suggestion

I would like any markdown document using the MyST extension, to only use the MyST implementation of any syntax/feature. Given that, it would be nice if there was a command like:

sphinx-myst --help directives    # MyST implemented directives
sphinx-myst --help syntax        # summary of commonly used markup
sphinx-myst --help extensions    # built-in extensions
sphinx-myst --help themes        # built-in themes

This would be similar to, but not limited to, the following examples:

pygmentize -L lexers
asciidoc --help syntax
# assuming bash shell
help
help case

The benefit would be, from the command line the user could get a quick overview of currently supported features and syntax, and hopefully it could be self-documenting and no developer time after the initial creation.

I'm working on a conversion project. Sphinx+MyST and the sphinx-book-theme have been a pleasure to use.

Thank you.

[agoose77]

There are a few questions to answer here. I'll start with distinguishing MyST-MD and MyST-Parser. MyST is a dialect of Markdown that adds useful features for scientific writing. These features were originally taken from ReST, but now MyST is evolving with its own specification (c.f. https://mep.mystmd.org and https://mystmd.org/spec).

myst-parser was the original implementation of a parser for the MyST syntax, and is designed to be used as part of the Sphinx ecosystem. Meanwhile, mystmd is a new project that steadily aims to implement something like Sphinx aimed towards scientific publication and technical communication. As such, the MyST dialect is common to both MyST-Parser and MyST-MD, but the implementations are separate. As a consequence of this, there are some subtle differences that follow from the different development paths of the projects. We (the EB team) are aiming to bring these implementations of MyST into well-defined agreement over time.

As for using the ~ character to start/end directives -- I'm not sure. I haven't seen this syntax used before, and a brief investigation of the mdit_py_plugins package suggests it requires : or `. However, I don't think these packages have changed too much since @chrisjsewell answered that issue, so I'd be surprised. Hopefully he can provide some better context than I can!

[72757373656c6c]

This was helpful. It's the names and the very similar websites that cloud the understanding. I knew "myst" (Markedly Structured Text) was a commonmark-based processor with sphinx rst implementations. I knew about myst-parser and sphinx from a "Talk Python to me" youtube video (which I'm going to rewatch), but I wasn't aware there were different variations of "myst". 🙃

As far as the tilde (~), besides issue 493, when I couldn't find it in the myst-parser.readthedocs.io documentation, I found it in myst_parser/mdit_to_docutils/base.py. I don't know if this makes it official and it just needs to be documented.

REGEX_DIRECTIVE_START = re.compile(r"^[\s]{0,3}([`]{3,10}|[~]{3,10}|[:]{3,10})\{")

As a Sphinx+MyST newbie, viewing mystmd.org mangled the learning curve. It should have been a clue when I saw the expandable boxes labeled, "Docutils and Sphinx Compatibility", which explained why the snippet I tried wasn't working. 😉

Thank you.