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 version

recommonmark 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 timeline

We 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:

• April 15, 2021: Post this issue and gather feedback
• April 30, 2021: Officially move forward with deprecation
  • Publish a transition guide with the basic steps required to migrate to 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.
  • Update the recommonmark repo README with a deprecation notice
  • Update the documentation with a deprecation notice
  • Release a new release to pypi with a deprecation notice and a deprecation notice in the code.
• By May 31, 2021: Work with the community to get documentation & references updated for recommonmark to recommend myst-parser
  • The Read the Docs documentation already did this
  • Sphinx markdown page
  • docutils beta markdown support
  • Other major references in the community that we can find

Changes for users

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 requested

• @lu-zero @pfultz2 @tqchen @sgenoud as the other major contributors
• @choldgraf @chrisjsewell as main developers of MyST-Parser
• @theacodes @ahopkins @LysandreJik @henryiii @Borda @cooperlees as maintainers of some high profile projects leveraging recommonmark
• @grubert as a docutils maintainer.
• @tk0miya as a sphinx maintainer

Thanks 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