This repository demonstrates an issue with the rst2myst
conversion tool.
The way rst2myst
translates rst substitutions to Markdown does not seem to work properly.
So far 2 inconsistencies have been identified:
-
rst2myst
relies on MyST ability to use Jinja2 for substitutions. Jinja2 requires a valid identifier (i.e., valid Python variable names), which is a much more restrictive condition, and therefore not compatible withrst
(e.g.rst
accepts strings with spaces) -
rst2myst
fails on translating links with substitutions (e.g.|ref|_
), which are a very common use case when writingrst
(e.g. for creating links with bold, italic or monospaced text elements)
This issue was first identified in
pyscaffold/pyscaffoldext-markdown#25.
An equivalent but minimal/simplified example can be found in original.rst
.
The following command was used to convert the file to
MyST-flavoured markdown, producing converted.md
.
$ rst2myst stream original.rst > converted.md
As we can see, converted.md
contains invalid Jinja2 syntax, e.g. {{ the repository service }}
, and the original link with substitution was converted
to a simple link, without a substitution.
Two different behaviours could be expected from rst2myst
:
- The "rst substitution key" could be pre-processed to produce a valid
Python identifier and in turn, that identifier could be used in Jinja2.
This include replacing or removing invalid characters, e.g.
|the repository service|
could be translated to{{ the_repository_service }}
. This approach in shown inexpected_option1.md
- The "rst substitution key" could be nested inside a dict value with an
arbitrary name (e.g.
__
), e.g.|the repository service|
could be translated to{{ __["the repository service"] }}
. This approach in shown inexpected_option2.md
Regarding links with substitutions, CommonMark's
full reference links
in combination with Jinja2 seem to be a good alternative, e.g.
|ref|_
could be translated to [{{ ref }}][ref]
. This approach is shown in
both expected_option1.md
and expected_option2.md
.
To run this example, you will need a Python virtual environment configured with the right dependencies. The following commands can be used to create one:
$ virtualenv -p py38 .venv
$ source .venv/bin/activate
$ pip install sphinx myst-parser 'rst-to-myst[sphinx]'
(A POSIX operating system an shell is also assumed)
The following commands can be used to compile the examples and serve HTML locally:
$ rst2myst stream original.rst > converted.md
$ make html
$ python3 -m http.server --directory _build/html