11

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?

barryhunter
  • 20,886
  • 3
  • 30
  • 43
Byte_Monster
  • 313
  • 3
  • 14

2 Answers2

22

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.

Wisco crew
  • 1,337
  • 1
  • 17
  • 25
  • 1
    to activate it, add it with '_' instead of '-' to the configuration: extensions = [ 'sphinx_markdown_tables', ] – 465b Jun 05 '20 at 09:01
7

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.

Waylan
  • 37,164
  • 12
  • 83
  • 109
  • Is it possible to do a markdown to rst conversion ? – DDGG May 17 '18 at 04:41
  • @DDGG probably. Presumably recommonmark converts the commonmark AST to a docutils document object. That can then be output to any output format that docutils supports (including rst). However, if no one has built a wrapper, you'll need to piece the parts together yourself, which might make for a good question. You might want to ask as a separate question. – Waylan May 21 '18 at 13:38