CODEWITHSUNDEEP
markdownpython-sphinxrestructuredtext
Byte_Monster
Byte_Monster

Reputation: 313

Sphinx is not recognising my markdown tables

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?

Upvotes: 11

Views: 4729

Answers (2)

Wisco crew
Wisco crew

Reputation: 1367

After searching unsuccessfully for ways to have Sphinx render tables authored in markdown, I wrote an extension to do it.

It is installable via pip install sphinx-markdown-tables.

Upvotes: 22

Waylan
Waylan

Reputation: 42497

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.

Upvotes: 7

Related Questions