Install & Compatibility
Where this runs
tested against v0.7.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.000s · 92.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.4s · import 0.000s · 93MB
95MB installed
● package 95MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
recommonmark
✓ extensions = ['recommonmark']
✗ from recommonmark.parser import CommonMarkParser; source_parsers = {'.md': CommonMarkParser}
The direct 'recommonmark' extension is preferred for Sphinx 1.4+; 'source_parsers' was deprecated in Sphinx 1.8 and removed in 3.0.
AutoStructify
✓ from recommonmark.transform import AutoStructify
Required for advanced Markdown-to-reStructuredText transformations like adding a Table of Contents.
To integrate recommonmark with Sphinx, you primarily add it to your `extensions` list in `conf.py`. For advanced features like automatic table of contents generation or embedding reStructuredText within Markdown, you must also import and register `AutoStructify` with specific configurations. This example also demonstrates how to enable `autosectionlabel` and prevent common conflicts.
# conf.py
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'My Project'
copyright = '2026, Your Name'
author = 'Your Name'
# The full version, including alpha/beta/rc tags
release = '0.1.0'
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.napoleon',
'sphinx.ext.autosectionlabel',
'recommonmark',
]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames. You can specify multiple suffix as a list of string:
source_suffix = ['.rst', '.md']
# The master toctree document.
master_doc = 'index'
# -- Options for AutoStructify (recommonmark's advanced features) -----------
from recommonmark.transform import AutoStructify
def setup(app):
app.add_config_value(
'recommonmark_config',
{
'enable_auto_toc_tree': True,
'enable_math': True,
'enable_inline_math': True,
'enable_eval_rst': True,
'enable_auto_doc_ref': True,
},
True,
)
app.add_transform(AutoStructify)
# Ensure that autosectionlabel prefixes document path to avoid conflicts
autosectionlabel_prefix_document = True
# -- Options for HTML output -------------------------------------------------
html_theme = 'alabaster'
# -- Generate a dummy index.md for demonstration --
# This would typically be an actual .md file in your source directory
with open('index.md', 'w') as f:
f.write('# Welcome to My Project\n\nThis is a Markdown file processed by recommonmark.\n\n## Features\n\n* Easy integration\n* Supports basic CommonMark\n* Advanced features via AutoStructify\n')
# To build the docs, run `sphinx-build -b html . _build` in a terminal where this conf.py exists.
Debug
Known issues
deprecatedrecommonmark is officially deprecated and no longer actively maintained. The recommended successor for integrating Markdown with Sphinx is MyST-Parser (https://myst-parser.readthedocs.io/). Users are strongly encouraged to migrate.fixMigrate your Sphinx project to use MyST-Parser. This may involve updating your `conf.py` and potentially adjusting some Markdown syntax for MyST-Parser's extended features.
affects: 0.7.1 and earlier
breakingSphinx 1.8 deprecated the `source_parsers` configuration variable, and Sphinx 3.0 removed it entirely. Older recommonmark setups that used `source_parsers = {'.md': CommonMarkParser}` will fail with newer Sphinx versions.fixFor Sphinx 1.4+, remove the `source_parsers` dictionary and instead add `'recommonmark'` directly to the `extensions` list in your `conf.py`. Ensure you are using `recommonmark` version 0.7.0 or newer if you are on Sphinx 1.8+.
affects: < 0.7.0 with Sphinx >= 1.8
gotchaUsing `sphinx.ext.autosectionlabel` alongside `recommonmark` can lead to 'duplicate label' warnings if multiple Markdown files have sections with the same title. By default, `autosectionlabel` creates labels based on the section title.fixTo prevent duplicate label warnings, set `autosectionlabel_prefix_document = True` in your `conf.py`. This prefixes section labels with the document name, creating unique labels. Alternatively, `suppress_warnings = ['autosectionlabel.*']` can hide these warnings, but it's generally better to resolve the underlying ambiguity.
affects: All versions
gotchaCommonMark (and thus recommonmark) does not inherently support many powerful Sphinx/reStructuredText features like the `toctree` directive, custom roles (`:ref:`, `:doc:`), or complex directives (e.g., for API documentation). While `AutoStructify` provides some bridges, full feature parity with reStructuredText is not available.fixFor content requiring deep Sphinx integration or complex directives, prefer reStructuredText (`.rst`) files. Use Markdown (`.md`) with recommonmark for prose-heavy content. Consider migrating to MyST-Parser, which offers more direct support for Sphinx directives within Markdown.
affects: All versions
gotchaSome CommonMark features like tables are not natively supported or reliably rendered by older versions of recommonmark or the underlying `commonmark-py` parser. This can lead to unexpected formatting or missing content in the generated documentation.fixFor rich Markdown features like tables, ensure `AutoStructify` is enabled and configured correctly, or consider using the MyST-Parser, which has better native support for such extensions, or even `sphinx-markdown-parser` for specific table support.
affects: All versions, particularly prior to 0.7.x
Upgrade
Version history
0.7.1latest on PyPI · released Dec 17, 2020
Audit
Dependencies
commonmarkrequiredCore CommonMark parser for Python.
docutilsrequiredDocutils tree generation and utilities.
sphinxrequiredIntegration with Sphinx documentation projects.