recommonmark

Warnings

• deprecated recommonmark 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.
  Fix: Migrate 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.
• breaking Sphinx 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.
  Fix: For 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+.
• gotcha Using `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.
  Fix: To 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.
• gotcha CommonMark (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.
  Fix: For 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.
• gotcha Some 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.
  Fix: For 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.

Install

• pip install recommonmark Install recommonmark

Imports

• recommonmark

  extensions = ['recommonmark']

  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.

Quickstart

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.