Jupyter-book: DOC: Add MyST syntax cheatsheet and comparison sheet

[mmcky]

Is your feature request related to a problem? Please describe.

Add a user friendly cheatsheet for writing MyST syntax.

It would be great if the cheat sheet could be accompanied by an "example" link in which
the same contents are displayed in rst, MyST, latex (and other possible source markup types)

Currently most details for MyST are located in the myst-parser docs but it would be nice to have a concise summary for users at the jupyter-book level as a single stop resource.

@najuzilu would you be willing to take a project like this on?

[choldgraf]

Yes, good idea! I wonder if we should have a section of pages on myst, rather than a single page. Does it make sense to add a sections group under our current myst page?

[najuzilu]

The cheat sheet would include rST → Markdown → MyST Markdown → Latex. One place in the documentation where all the different source files are mentioned is under Types of content source files. We can add a section there.

Another option would be to have a page under the "Write book content" header before MyST Markdown Overview. It could be titled "MyST Cheat Sheet".

I prefer the latter but am open to other suggestions.

[najuzilu]

We could also split the two and include "MyST Cheat Sheet" and "MyST Comparison Sheet". The first would be a quick recap to useful MyST syntax (similar to the Conda cheat sheet). The other would be the syntax conversion from rST → Markdown → MyST Markdown → Latex.

[choldgraf]

I'm a +1 on two cheat sheets - one for common and useful syntax in MyST, and another for a full comparison (which I'd see as more of an advanced feature...we don't want to put rST or Latex in front of new users IMO)

[najuzilu]

I like @chrisjsewell's work on the MyST syntax here. If it's okay with @chrisjsewell I would like to copy over some of his work and rearrange/update it to include specific examples.

Here's what I have in mind not necessarily in this order:

• header
• target headers
• quote
• list
• thematic break
• block break
• line comment
• table
• math - inline (single and multiline) and directives with labels and equation referencing
• code block - executable and non executable (should we include tags too?)
• html block
• figure/image - inline, image and figure directives with labels and example how to reference it
• footnotes
• citations
• admonitions including note, warning, tip, caution directives
• glue feature

What do others think? @jstac @thomassargent30 @choldgraf

[chrisjsewell]

I would like to copy over some of his work and rearrange/update it to include specific examples

Yeh happy for you to use and abuse it 😄 We may want to take the opportunity though to decide on the general organization of documentation, specifically which documentation should be in jupyter-book, myst-nb, myst-parser (+markdown-it-py) etc; do we duplicate or have a central source?

I'm literally just involved in a document restructuring effort for another project actually; the structure we decided on there may be of interest: https://github.com/aiidateam/aiida-core/wiki/Writing-documentation#how-the-aiida-documentation-is-organized

Note also there is this project for centralizing documentation improvements https://github.com/orgs/executablebooks/projects/4.

[jstac]

Thanks for the list @najuzilu . It looks great to me. Others will add more over time.

The target users @thomassargent30 and I had in mind when we suggested a cheat sheet are people getting started with Jupyter Book. The syntax most helpful to such people would be MyST / MyST-NB. For example, code blocks should be

```{code-cell} ipython3 xyz ```

Rather than

```{code-block} python xyz ```

The aim is to help people write books in JB easily, not be a pure resource on MyST --- that's better off left to the MyST documentation.

In terms of where we put this, I don't mind.

Perhaps a good starting point is to make something similar to https://docutils.sourceforge.io/docs/user/rst/quickref.html (but hopefully looking nicer :-)

[choldgraf]

this is now finished by @najuzilu and documented here! https://jupyterbook.org/reference/cheatsheet.html