Sphinx Markdown Builder

0.6.10 · active · verified Tue Apr 14

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.

Warnings

breaking 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.
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.
breaking Support for older Python versions has been dropped in recent releases. For example, Python 3.6 support was removed in v0.6.0.
Fix: Ensure your Python environment is 3.7 or newer. Upgrade your Python version if using an older version.
gotcha 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.
Fix: To ensure `.md` extensions, configure `markdown_builder_uri = "{path}.md"` in your `conf.py` file.

Install

pip install sphinx-markdown-builder Install latest version

Quickstart

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.

# Save this as docs/conf.py (after running sphinx-quickstart)
import os
import sys
# Assuming your Sphinx project root is 'docs'
sys.path.insert(0, os.path.abspath('.'))

project = 'My Markdown Docs'
copyright = '2024, AI Assistant'
extensions = [
    'sphinx_markdown_builder',
    # Other Sphinx extensions can go here, e.g., 'sphinx.ext.autodoc'
]

# Configure output Markdown file extension
markdown_builder_uri = '{path}.md'

# Minimal settings for Markdown output
# Add other Sphinx standard configurations as needed
html_theme = 'alabaster' # A theme is typically required by Sphinx init

# Example index.rst content (save as docs/index.rst):
# ===================
# My Markdown Docs
# ===================
#
# Hello World!

view raw JSON →