---
id: recommonmark
version: "0.7.1"
license: MIT
license_treatment: permissive
maintenance: abandoned
---

# recommonmark — A docutils-compatibility bridge to CommonMark, enabling you to write CommonMark inside of Docutils & Sphinx projects.

License: permissive · Maintenance: abandoned · Downloads: 1.2M/mo

## What it is and what it does

recommonmark is a parser that lets Sphinx and Docutils projects write documentation in CommonMark (Markdown) instead of only reStructuredText. It acts as a bridge between the CommonMark syntax and Docutils' internal document model, allowing you to mix .md and .rst files in the same project and use Sphinx features like cross-references and auto-generated table of contents from Markdown headings.

The package includes AutoStructify, an optional component that can automatically transform Markdown into reStructuredText at build time, with support for features like automatic table-of-contents generation, math formulas, and embedded reStructuredText evaluation. However, the project is now deprecated and archived; its maintainers recommend using an alternative for new work.

Use it for:

- Adding Markdown documentation files to an existing Sphinx project without rewriting everything in reStructuredText.
- Using AutoStructify to automatically generate table-of-contents and cross-reference structures from Markdown headings during the Sphinx build.
- Migrating documentation from a Markdown-based system to Sphinx while keeping Markdown as the source format during transition.
- Enabling teams familiar with Markdown to contribute to Sphinx-based documentation without learning reStructuredText syntax.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Enables Sphinx and Docutils projects to parse and render CommonMark (Markdown) files alongside reStructuredText, bridging CommonMark syntax to the Docutils document model.

No. The package is abandoned (last commit 2021-05-18) and its maintainers explicitly recommend an alternative. While it has low install friction and no known vulnerabilities, the lack of ongoing maintenance means no compatibility fixes for current Sphinx versions and no security updates.

## Install

pip install recommonmark
uv add recommonmark
poetry add recommonmark

## Installing recommonmark

Before you install: Low install friction with a pure-Python wheel, but the package is abandoned as of 2021-05-18 with no maintenance since. The maintainers explicitly recommend a replacement for new projects.

License in practice: MIT license permits commercial and private use with minimal restrictions, though the abandoned status means no security or compatibility updates are forthcoming.

Quickstart:

pip install recommonmark

# In Sphinx conf.py:
extensions = ['recommonmark']

# Then write .md files alongside .rst in your documentation source.

Requires Sphinx and Docutils; abandoned since 2021-05-18 with no ongoing maintenance or security updates.

Verify before relying:

- Whether existing Sphinx projects using recommonmark will continue to work with current Sphinx versions without compatibility issues.
- Whether the AutoStructify component's advanced Markdown-to-reStructuredText transformations are still reliable for complex documentation.

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: abandoned
- Downloads: 1.2M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

markdown support for sphinx, commonmark docutils bridge, write markdown in sphinx projects, markdown to docutils parser, sphinx markdown integration, deprecated, markdown-to-rst

[View on SkillFed](https://skillfed.io/packages/recommonmark) · [View on PyPI](https://pypi.org/project/recommonmark/)