Suggestions for Executable Markdown Files Documentation

[mforbes]

trafficstars

While trying to read through and follow the Executable Markdown Files docs, I ran into some issues that could be clarified:

1. To run code, you must install at least jupyter in addition to mystmd. This is almost obvious, but not completely transparent from the quickstart repo, since it installs jupyterlab_myst which in turn pulls in jupyter.
2. It would be helpful to remind the reader that frontmatter needs to appear between --- pairs.
3. LANGUAGE defines the language to be used in executing the code. This implies that you can select different kernels in the code cells by specifying LANGUAGE, which (I think) is not currently the case (see also https://github.com/orgs/executablebooks/discussions/1137). Other similar language exists in the page: as far as I can tell, one cannot use multiple kernels, and LANGUAGE is just used for code formatting - is this still true?
4. For someone not intimately familiar with ipykernel, the mean of the kernel name and display_name is quite mysterious. I suggest including either a margin-note or admonition explaining how to find out what names are valid...: This is included below jupyter kernelspec list I suggest just including this in the table.

I will include more as I work though, then submit a PR.

[mforbes]

Part of my confusion was that I somehow jumped to Executable Markdown Files first instead of Executable Documents. The latter is somewhat clearer.

Maybe this is simply point to to the latter, and/or adding a Prerequisites section to the former with something like:

Prerequisites: This assumes you’ve completed Get Started, know how to set Frontmatter, and have MyST installed locally with jupyter along with any other kernels or packages you need to execute your code.

Is a "Goals and prerequisites" section appropriate for Executable Markdown Files, or are those reserved for quickstart files?

[rowanc1]

I put up a few improvements in #1852. I think there are still more needed and would love help from you!