Hey folks, with a sad heart I feel like it's probably time to write this update and make it official. We are planning to officially end support for recommonmark in the near future, and I wanted to give folks a chance to give us feedback on this proposal. We generally recommend everyone to switch to MyST-Parser instead -- read below for more background and a proposed timeline.
Long versionrecommonmark is built on top of commonmark.py (originally CommonMark-py by @rolandshoemaker) to fill a gap that we observed in the ecosystem: many people wanted to write their Sphinx documentation using Markdown. We are happy to see that so many projects use it nowadays: there is no better confirmation that our observation was true.
However, the project has been quite inactive for the past two years (with a minor update on December 2020 to fix an annoying bug), and we have not been responsive enough to bug reports and feature requests. Besides, the landscape of Markdown on Sphinx has changed quite dramatically in recent times: out of frustration for the lack of CommonMark-compliant, extensible Markdown parsing libraries in Python, the Executable Books project has created MyST-Parser, a project that goes beyond the original goals of recommonmark, extends Markdown to add useful features present in reStructuredText, and enjoys excellent community support.
For the reasons outlined above, we would like to effectively deprecate recommonmark and encourage users to migrate their documentation to MyST-Parser. We acknowledge that this migration can take some effort, and that users might miss some features currently not available on MyST-Parser like AutoStructify, but we think it is in the best interest for the community to consolidate interest around the most active and promising alternative.
Plans and timelineWe are currently posting this to the recommonmark GitHub repo, and we'll ask for feedback through our various channels.
The goal it to make sure the transition is as seemless as possible,
so the current proposed timeline is:
myst-parser for users. We hope this should be a small adjustment, but there are some syntax differences that might take a bit of time to resolve.recommonmark repo README with a deprecation noticerecommonmark to recommend myst-parser
Of note, the published pypi packages will continue to work. We don't plan to remove them, or remove the documentation for older versions of the packages. This change will only mean that new versions of the package will not be released.
If you are happy with the current implementation, you are welcome to continue using it without support.
Feedback requestedThanks again for working with us to advance the state of markdown in Sphinx, and we hope to continue to build support around this idea with MyST.
Update: translation help@jpmckinney posted a script in the thread to help convert:
In case it's useful to others, I had hacked together this one-time script to convert recommonmark eval_rst blocks: https://gist.github.com/jpmckinney/88c846651ab5411d1ed3a6fe222ce08f/e8f5c6febc147c512990ab3ab8809386a9b7d765
@chrisjsewell also have a repo to help: https://github.com/executablebooks/rst-to-myst
tannewtastrojuanlu, john-hen, choldgraf, ahopkins, lu-zero and 4 morehenryiii, cooperlees, ichard26, choldgraf, tk0miya and 1 more
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4