DEV Community


Posted on • Updated on

Convert Markdown into HTML with Sphinx

Little notes of a study on a method to convert a markdown file into a HTML file with Sphinx. You can find the deliverable of this study in sphinx-with-markdown.

Enable markdown syntax in Sphinx

Install recommonmark and register it as a markdown parser.

pip install recommonmark
Enter fullscreen mode Exit fullscreen mode

source_suffix = ['.rst', '.md']
source_parsers = {
   '.md': 'recommonmark.parser.CommonMarkParser',
Enter fullscreen mode Exit fullscreen mode

Activate AutoStructify component that enables the eval_rs syntax to embed reStructuredText in markdown and syntax highlighting by adding the following configuration in

from recommonmark.transform import AutoStructify
def setup(app):
    app.add_config_value('recommonmark_config', {
            'auto_toc_tree_section': 'Contents',
            }, True)
Enter fullscreen mode Exit fullscreen mode

Install sphinx_markdown_tables as recommonmark by itself doesn't support markdown table syntax.

pip install sphinx-markdown-tables
Enter fullscreen mode Exit fullscreen mode

extensions = [
Enter fullscreen mode Exit fullscreen mode

Internationalization (Multilingualization)

Sphinx has an internationalization feature (sphinx-intl) on top of gettext.

pip install sphinx-intl
Enter fullscreen mode Exit fullscreen mode
# Compile messages to translate from source code in pot files in {build dir}/gettext.
make gettext
# Generate po files from pot files in {source dir}/locale.
sphinx-intl update -p build/gettext -l en

# Edit the generated po files.

# Specify a language and generate translated documents. 
make -e SPHINXOPTS="-D language='en'" html
Enter fullscreen mode Exit fullscreen mode

When you update the document, you can update po files in the same way.

Edit a PO file

PoEdit is a easy-to-use editor though its complementary version has several feature limitations.


HTML Themes

Various HTML themes can be found in

Read the Docs theme seems to be popular among sphinx users.

Docker Image

There are several images in DockerHub which set up sphinx, but none of them seems to be maintained well. Therefore I chose to build my own image from python official image (alpine).

  • hnakamur/sphinx
    • The version of installed sphinx is still 2.0.1 (latest version is 2.1.2.).
  • docker-sphinx-rtd-theme
    • You can use the latest sphinx as its version is not specified in Dockerfile.
    • Python is a little old (3.6), and sphinx-intl is not installed.
  • plaindocs/docker-sphinx
    • Pushed once 4 years ago. Its image size is relatively large as it is based on Ubuntu.

Known Issues

  • The markdown list syntax * item is converted into <li><p>item</p></li>, resulting in generating additional p element and causing styling problems in some HTML templates.
  • Inline styles will be deleted when converting into po files, and they need to be added manually in reST syntax.


Avoid Warnings on toctree

Sphinx generates a warning when it finds a document which is not included in any toctree.

checking consistency... C:\Users\xxx\Desktop\sx\source\ WARNING: document isn't included in any toctree
Enter fullscreen mode Exit fullscreen mode

To suppress the warning, add orphan in the first line of the document.

Other Useful Packages

  • Export documents in ePub format: pip install Pillow
  • Watch changes on documents and re-build automatically: pip install sphinx-autobuild


Top comments (1)

ooooo profile image

convert markdown to html online is also a good choice