{"id":6245,"library":"sphinx-markdown-builder","title":"Sphinx Markdown Builder","description":"sphinx-markdown-builder is a Sphinx extension that enables the generation of documentation in Markdown format. It extends Sphinx's build capabilities, allowing users to build their existing reStructuredText or MyST Markdown projects into standard Markdown files. The current version is 0.6.10, and it generally follows a release cadence tied to major Sphinx versions and critical bug fixes.","status":"active","version":"0.6.10","language":"en","source_language":"en","source_url":"https://github.com/liran-funaro/sphinx-markdown-builder","tags":["Sphinx","documentation","Markdown","builder","extension"],"install":[{"cmd":"pip install sphinx-markdown-builder","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for building documentation as a Sphinx extension, typically Sphinx >= 4.0.0.","package":"Sphinx","optional":false}],"imports":[],"quickstart":{"code":"# Save this as docs/conf.py (after running sphinx-quickstart)\nimport os\nimport sys\n# Assuming your Sphinx project root is 'docs'\nsys.path.insert(0, os.path.abspath('.'))\n\nproject = 'My Markdown Docs'\ncopyright = '2024, AI Assistant'\nextensions = [\n    'sphinx_markdown_builder',\n    # Other Sphinx extensions can go here, e.g., 'sphinx.ext.autodoc'\n]\n\n# Configure output Markdown file extension\nmarkdown_builder_uri = '{path}.md'\n\n# Minimal settings for Markdown output\n# Add other Sphinx standard configurations as needed\nhtml_theme = 'alabaster' # A theme is typically required by Sphinx init\n\n# Example index.rst content (save as docs/index.rst):\n# ===================\n# My Markdown Docs\n# ===================\n#\n# Hello World!\n","lang":"python","description":"To quickly generate Markdown from your Sphinx project, first create a basic Sphinx project (e.g., `sphinx-quickstart docs`). Then, modify `docs/conf.py` to include `sphinx_markdown_builder` in your `extensions` list and set `markdown_builder_uri = '{path}.md'` for correct file extensions. Finally, run `sphinx-build -b markdown docs _build/markdown` from your project's root directory to generate Markdown output."},"warnings":[{"fix":"Upgrade `sphinx-markdown-builder` to a version that explicitly supports your Sphinx version. Check the package's release notes or GitHub page for detailed compatibility information.","message":"Major version bumps for Sphinx (e.g., Sphinx 7.x support added in v0.6.0, Sphinx 5.x/6.x in v0.5.0) often require corresponding `sphinx-markdown-builder` updates. Using an incompatible version can lead to build failures.","severity":"breaking","affected_versions":"Before v0.6.0 (for Sphinx 7.x); before v0.5.0 (for Sphinx 5.x/6.x); generally any version mismatch."},{"fix":"Ensure your Python environment is 3.7 or newer. Upgrade your Python version if using an older version.","message":"Support for older Python versions has been dropped in recent releases. For example, Python 3.6 support was removed in v0.6.0.","severity":"breaking","affected_versions":"v0.6.0 and later"},{"fix":"To ensure `.md` extensions, configure `markdown_builder_uri = \"{path}.md\"` in your `conf.py` file.","message":"By default, `sphinx-markdown-builder` generates Markdown files with a `.rst` extension in the output directory, which can be confusing if you expect standard `.md` files.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}