Runtime errors¶
“&” character in the URL breaks links¶
A link in the documentation set is broken when the URL contains an “&” character. For example, a link to https://example.com/?param1=value1¶m2=value2 may be rendered as https://example.com/?param1=value1&param2=value2 in the generated HTML, causing the link to break.
Cause¶
This is a known bug that has been resolved in the myst-parser extension. However, the latest version of the extension is incompatible with the Sphinx Stack, which retains support for Python 3.10 and Sphinx 7.
Resolution¶
In .rst sources, keep & in the URL; Sphinx will escape it correctly in the generated HTML. For example: https://example.com/?param1=value1¶m2=value2.
If you are using MyST, add the link in an eval-rst directive. You may also want to include a comment explaining the workaround so it’ll be easier to undo later on.
```{eval-rst}
.. This URL includes an & which is broken by the current version of myst-parser (fixed in v5.1.0)
`Link text <https://example.com/?param1=value1¶m2=value2>`_
```