Sphinx is not recognising my markdown tables

Question

I am using sphinx locally with .md files. When I add a table in the format:

| something | something else | something more |

| one | two | three |

the text is getting parsed as a paragraph. I have tried with rst files and it works in this format:

===== ===== ====

oneee ttttt ffff

===== ===== ====

sdddd dfvgd sdfv

dfgvv dffff ffff

===== ===== ====

When I am using rst files I am getting error messages about wrongly structured tables while in md files it goes silent.

Any ideas?

Answer 1

In short, standard Markdown has no support for tables and never has. You will need to use RST for tables.

As the Sphinx documentation notes:

To support Markdown-based documentation, Sphinx can use recommonmark. recommonmark is a Docutils bridge to CommonMark-py, a Python package for parsing the CommonMark Markdown flavor.

In fact, a review of the CommonMark spec reveals no mention of tables. For that matter, the original Markdown rules never mentioned tables either. Regardless, over the years various Markdown implementations have added support for tables in various ways, one of the more well known being GitHub. In fact, GitHub has published their own extensions to the CommonMark spec which add support for tables. However, recommonmark/CommonMark-py does not use that spec, but the standard CommonMark spec, so there is no table support.

I checked the documentation for both recommonmark and CommonMark-py, but neither appear to support tables as an option either. However, recommonmark does add some Sphinx specific functionality, which is off by default. While they mostly have to do with autogenerated table of contents and math, there is the enable_eval_rst option which, if enabled, allows you to embed RST right in your Markdown document. You may be able to include a RST table right in a Markdown document with that feature enabled.