executablebooks / rst-to-myst

Convert ReStructuredText to MyST Markdown
https://rst-to-myst.readthedocs.io
MIT License
64 stars 11 forks source link

Target ids are sanitised, so may not align with e.g. references in `ref` roles #16

Open mbercx opened 3 years ago

mbercx commented 3 years ago

Describe the bug

Underscores _ inside a target header seem to get converted into hyphens -, but not for the references. E.g. this .rst snippet:

.. _test_snippet:

.. code-block:: Python

    # This is a test snippet.

Dude, check out that :ref:`test snippet <test_snippet>`!

Gets converted into:

(test-snippet)=

```{code-block} Python

# This is a test snippet.

```#

Dude, check out that {ref}`test snippet <test_snippet>`!

Expected behavior

Either the underscores should be preserved, or both the target header and references should be converted into hyphens, in case this is preferred.

Environment

chrisjsewell commented 3 years ago

Heya, docutils id creation is defined here: https://github.com/chrisjsewell/docutils/blob/8adab0660b2097b4f3c32cef7e5ff4cb3c72b084/docutils/docutils/nodes.py#L2196; basically every non-alphanumeric character gets converted to a -, and so actually test_snippet should still match test-snippet (although let me know if you think this is not the case)

I'm going to mark this therefore as an documentation/improvement issue, not a bug; it would be nice to align them, but its a bit tricky to achieve in the code