howto produce a myst/markdown format

[parmentelat]

Hi, I'd like to give the myst markdown variant a try

https://jupytext.readthedocs.io/en/latest/formats.html?highlight=myst#myst-markdown

but have not been able to find the right syntax, here's what I tried

$ jupytext --set-formats markdown:myst  my-notebook.md
[jupytext] Reading w9-s2-c1-decorateurs.md
[jupytext] Updating notebook metadata with '{"jupytext": {"formats": "markdown:myst"}}'
<stack-trace>
jupytext.formats.JupytextFormatError: myst is not a valid format name. Please choose one of light, pandoc, spin, hydrogen, markdown, nomarker, sphinx, rmarkdown, percent

as a side question, I have just obtained this my-notebook.md by running

$ jupytext --to markdown my-notebook.ipynb

and am a little confused as to which specific markdown variant is being used; the .md file reads like this

---
jupyter:
  jupytext:
    formats: md
    text_representation:
      extension: .md
      format_name: markdown

thanks again for the awesome tool !

[mwouts]

Hi @parmentelat , if you want to convert a given notebook to the myst format, then you can do:

jupytext --to md:myst notebook.ipynb

If you want to pair the two files, then you can either use the extension (Jupytext Menu, or Jupytext commands in JLab), or:

jupytext --set-formats md:myst,ipynb notebook.ipynb

and am a little confused as to which specific markdown variant is being used; the .md file reads like this

format_name: markdown is Jupytext's default Markdown format (sorry the name is a big generic, I did not imagine at that time that we were going to have multiple Markdown formats... 😄 ). For Myst-Markdown instead you will get format_name: myst.

thanks again for the awesome tool !

My pleasure! I hope the above helps. If you don't mind, can you tell me where you would have expected to find the information that was missing here? Would you recommend updating the doc / jupytext --help, or both?

[parmentelat]

Hi again; it looks like my installation is off, because typing your exact sentence gives me the same

$ jupytext --to md:myst w9-s2-c1-decorateurs.ipynb
Traceback (most recent call last):
<>
jupytext.formats.JupytextFormatError: myst is not a valid format name. Please choose one of pandoc, spin, percent, nomarker, light, markdown, sphinx, rmarkdown, hydrogen

I had already upgraded to the latest, and I am using this version

$ jupytext --version
1.5.1

is there a specific variant that I need to pass to
pip install jupytext[something]
?

[mwouts]

Oh sure! It's pip install jupytext[myst] - this will install myst-parser.
Sorry the error message is misleading, I'll see how I can improve that.

[parmentelat]

ah <mental slap on the forehead> !
stupid me then :)

[chrisjsewell]

yes this is something that maybe I'd like to remove the need for in the future actually: if I can get the conversion done without any dependencies, it wouldn't add this extra hassle.
Out of interest @mwouts, if the only dependency was markdown-it-py, which itself only has a dependency on the widely used attrs, would you consider allowing it to be added to the required installs, rather than in the extras?

[mwouts]

Hi @chrisjsewell, sure I will think about it (and ask the IT department at work how easy for them it is to install markdown-it-py...). And at the very least, I will make sure that the error message says explicitly that one just needs to install myst.

[chrisjsewell]

thanks @mwouts

[mwouts]

I will make sure that the error message says explicitly that one just needs to install myst.

Hi @chrisjsewell , I have a PR for that at #584 , do you want to have a look at it?

[mwouts]

Closing as #584 was merged - the error message will be much more informative now.