Sphinx Markdown Tables

0.0.17 · active · verified Thu Apr 16

sphinx-markdown-tables is a Sphinx extension designed to render tables written in GitHub Flavored Markdown (GFM) within Sphinx documentation projects. It enables users to utilize familiar Markdown table syntax for documentation generated by Sphinx. The current version is 0.0.17. While not on a strict release cadence, it receives updates for bug fixes and compatibility with new Sphinx versions.

Common errors

```
Unknown extension: 'sphinx_markdown_tables'
```
cause The `sphinx_markdown_tables` string was not correctly added to the `extensions` list in `conf.py`, or there's a typo in the extension name.

fix Check your `conf.py` file to ensure `sphinx_markdown_tables` is present and correctly spelled within the `extensions = [...]` list.
```
Markdown tables not rendering or appearing as raw text in the output HTML/PDF.
```
cause Either `sphinx_markdown_tables` is not enabled, or more commonly, Sphinx isn't configured to parse `.md` files at all (e.g., `myst_parser` is missing or not configured).

fix 1. Verify `sphinx_markdown_tables` is in `extensions` in `conf.py`. 2. If using Markdown files (`.md`), ensure a Markdown parser like `myst_parser` is installed (`pip install myst-parser`) and also added to `extensions` in `conf.py`, and `source_suffix` is configured for `.md`.
```
ModuleNotFoundError: No module named 'sphinx_markdown_tables'
```
cause The `sphinx-markdown-tables` package is not installed in the Python environment where Sphinx is being run to build your documentation.

fix Install the package using `pip install sphinx-markdown-tables`. Ensure you are running Sphinx in the correct virtual environment if applicable.

Warnings

gotcha Using `sphinx-markdown-tables` with `.md` files requires an additional Markdown parsing extension (e.g., `myst_parser`) to be enabled in `conf.py`.
Fix: Ensure you have `myst_parser` (or similar) installed (`pip install myst-parser`) and added to your `extensions` list in `conf.py` alongside `sphinx_markdown_tables`. Also configure `source_suffix` to include `.md`.
gotcha While generally compatible, ensure `sphinx-markdown-tables` is compatible with your specific Sphinx version, especially when using pre-release or very new Sphinx versions. Major Sphinx upgrades can sometimes introduce changes that affect extensions.
Fix: If issues arise after a Sphinx upgrade, check the `sphinx-markdown-tables` GitHub issues for known compatibility problems or try updating `sphinx-markdown-tables` to its latest version.
gotcha `sphinx-markdown-tables` specifically supports GitHub Flavored Markdown (GFM) table syntax. Other Markdown table syntaxes (e.g., reStructuredText's `.. list-table::`) are not supported through this extension for Markdown files.
Fix: Adhere to the GFM table syntax in your Markdown files for correct rendering. Example: `| H1 | H2 |\n|----|----|\n| C1 | C2 |`

Install

pip install sphinx-markdown-tables Install latest version

Quickstart

To use `sphinx-markdown-tables`, add it to the `extensions` list in your Sphinx `conf.py`. This example also includes `myst_parser`, which is commonly used to enable Sphinx to parse Markdown files (`.md`). After configuration, you can use GitHub Flavored Markdown (GFM) table syntax in your Markdown source files, and Sphinx will render them as HTML tables.

# conf.py
# Minimal Sphinx configuration for sphinx-markdown-tables
# Make sure you have 'myst_parser' installed if using .md files.
# pip install myst-parser

project = 'My Markdown Tables Project'
copyright = '2024, Example Author'
extensions = [
    'myst_parser', # Required for Sphinx to parse .md files
    'sphinx_markdown_tables' # The extension itself
]
# You would also set source_suffix appropriately, e.g.,
source_suffix = {
    '.rst': 'restructuredtext',
    '.md': 'markdown',
}
html_theme = 'alabaster' # Or any other Sphinx theme

# Example index.md content for using markdown tables:
# ```markdown
# # My Document
# 
# Here is a table:
# 
# | Header 1 | Header 2 | Header 3 |
# |----------|----------|----------|
# | Row 1 Col 1 | Row 1 Col 2 | Row 1 Col 3 |
# | Row 2 Col 1 | Row 2 Col 2 | Row 2 Col 3 |
# ```

view raw JSON →