Including a README.md with links that contain `&`s, "translates them" to `&`

[stdedos]

Description

With README.md of

# Title

[![CalVer v0.2.0+2022.09.1000][version_img]][version_url]

[version_img]: https://img.shields.io/static/v1.svg?label=CalVer&message=v0.2.0+2022.09.1000&color=blue
[version_url]: https://pypi.org/project/bumpver/

Url https://img.shields.io/static/v1.svg?label=CalVer&message=v0.2.0+2022.09.1000&color=blue is rendered as https://img.shields.io/static/v1.svg?label=CalVer&message=v0.2.0+2022.09.1000&color=blue, breaking linkage

Details

• OS: debian/buster
• Python version: 3.9
• Project version: sphinx_mdinclude 0.5.2
• Can you repro on main? N/A
• Can you repro in a clean virtualenv? Yes (? - repro is done on CI)

[veenstrajelmer]

@amyreese I am running into the same issue. Would it be complex to fix? I looked into the code, but would not know how to solve it directly

[veenstrajelmer]

I did a lot of digging in the sphinx-mdinclude and mistune code and found that this is because of an issue in mistune: https://github.com/lepture/mistune/issues/372

I am not sure if it will be resolved there, but if it will it will probably only be resolved in mistune>3.0. sphinx-mdinclude requires mistune 2 at the moment. A sort of decent alternative is to add some replacements to the RestRenderer class:

• Restrenderer.link: link = link.replace("&","&")
• Restrenderer.image: src = src.replace("&","&")
• maybe also for other class functions

These replacements will result in the desired outputs for these two usecases:

from sphinx_mdinclude.render import convert
src = "[A link with ampersand](https://sonarcloud.io/api/project_badges/measure?project=Deltares_ddlpy&metric=alert_status)"
out = convert(src)
print(out)

src = "[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=Deltares_ddlpy&metric=alert_status)](https://sonarcloud.io/summary/overall?id=Deltares_ddlpy)"
out = convert(src)
print(out)

[veenstrajelmer]

Since sphinx-mdinclude now supports mistune>=3, I think the issue should be resolved in mistune. I will update my findings in https://github.com/lepture/mistune/issues/372

[veenstrajelmer]

These issues are probably resolved with mistune PR's https://github.com/lepture/mistune/pull/393 and https://github.com/lepture/mistune/pull/395 by @mentalisttraceur