{"id":4231,"library":"recommonmark","title":"recommonmark","description":"recommonmark provides a compatibility bridge to CommonMark, allowing users to write Markdown files within Docutils and Sphinx projects. It parses CommonMark-compliant Markdown into a Docutils abstract syntax tree, integrating it into the Sphinx build process. The library's last release was in December 2020, and it is officially deprecated in favor of MyST-Parser.","status":"deprecated","version":"0.7.1","language":"en","source_language":"en","source_url":"https://github.com/rtfd/recommonmark","tags":["markdown","sphinx","docutils","documentation","deprecated"],"install":[{"cmd":"pip install recommonmark","lang":"bash","label":"Install recommonmark"}],"dependencies":[{"reason":"Core CommonMark parser for Python.","package":"commonmark","optional":false},{"reason":"Docutils tree generation and utilities.","package":"docutils","optional":false},{"reason":"Integration with Sphinx documentation projects.","package":"sphinx","optional":false}],"imports":[{"note":"The direct 'recommonmark' extension is preferred for Sphinx 1.4+; 'source_parsers' was deprecated in Sphinx 1.8 and removed in 3.0.","wrong":"from recommonmark.parser import CommonMarkParser; source_parsers = {'.md': CommonMarkParser}","symbol":"recommonmark","correct":"extensions = ['recommonmark']"},{"note":"Required for advanced Markdown-to-reStructuredText transformations like adding a Table of Contents.","symbol":"AutoStructify","correct":"from recommonmark.transform import AutoStructify"}],"quickstart":{"code":"# conf.py\n\nimport os\nimport sys\nsys.path.insert(0, os.path.abspath('.'))\n\n# -- Project information -----------------------------------------------------\nproject = 'My Project'\ncopyright = '2026, Your Name'\nauthor = 'Your Name'\n\n# The full version, including alpha/beta/rc tags\nrelease = '0.1.0'\n\n# -- General configuration ---------------------------------------------------\n\n# Add any Sphinx extension module names here, as strings. They can be\n# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom\n# ones.\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinx.ext.autosectionlabel',\n    'recommonmark',\n]\n\n# Add any paths that contain templates here, relative to this directory.\ntemplates_path = ['_templates']\n\n# The suffix(es) of source filenames. You can specify multiple suffix as a list of string:\nsource_suffix = ['.rst', '.md']\n\n# The master toctree document.\nmaster_doc = 'index'\n\n# -- Options for AutoStructify (recommonmark's advanced features) -----------\nfrom recommonmark.transform import AutoStructify\n\ndef setup(app):\n    app.add_config_value(\n        'recommonmark_config',\n        {\n            'enable_auto_toc_tree': True,\n            'enable_math': True,\n            'enable_inline_math': True,\n            'enable_eval_rst': True,\n            'enable_auto_doc_ref': True,\n        },\n        True,\n    )\n    app.add_transform(AutoStructify)\n\n# Ensure that autosectionlabel prefixes document path to avoid conflicts\nautosectionlabel_prefix_document = True\n\n# -- Options for HTML output -------------------------------------------------\nhtml_theme = 'alabaster'\n\n# -- Generate a dummy index.md for demonstration --\n# This would typically be an actual .md file in your source directory\nwith open('index.md', 'w') as f:\n    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')\n\n# To build the docs, run `sphinx-build -b html . _build` in a terminal where this conf.py exists.\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"deprecated","affected_versions":"0.7.1 and earlier"},{"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+.","message":"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.","severity":"breaking","affected_versions":"< 0.7.0 with Sphinx >= 1.8"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, particularly prior to 0.7.x"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}