Skip to content

Rendering CSV as Markdown table in Mkdocs Material#

Markdown table is not easy to write in IDE. So I want to write CSV and render it as Markdown table. Previously I used a pre-build script during CICD time to convert CSV to Markdown table, and referenced it as --8<-- "markdown_table_file_path.md". But it's not convenient to preview the result locally. So I want to find a way to render CSV as Markdown table in Mkdocs Material directly.

Thanks to pymdown-extensions maintainer @facelessuser, he gave me some tips.

  1. In Markdown file, use code block with language csv to render CSV as Markdown table.

    ```csv-path
my_csv_file_path.csv
```

  2. In mkdocs.yml, add custom fence for csv-path language:

    - pymdownx.superfences:
  custom_fences:
    - name: csv-path
      class: csv-path
      format: !!python/name:tools.pymdownx_md_render.md_csv_path_render

  3. Install additional pip dependencies:

    # if you use other methode to convert csv to markdown table,
# you may need to install other modules
pip install pandas, tabulate

  4. In tools/pymdownx_md_render.py, add a new function md_csv_path_render() to handle csv code block. Check here to see a pymdownx_md_render.py example.

    tablefmt="github" is to set the alignment.

    file tools/pymdownx_md_render.py
    ... other imports
import pandas as pd

... other functions

def md_csv_path_render(
        src="",
        language="",
        class_name=None,
        options=None, md="",
        **kwargs):
    """Formatter wrapper."""
    try:
        df = pd.read_csv(src)
        return markdown.markdown(
            df.to_markdown(tablefmt="github", index=False),
            extensions=["tables"])
    except Exception:
        import traceback

        print(traceback.format_exc())
        raise

    We can use other modules (for e.g. csv2md) than pandas as pandas is a little heavy

    # no need to pip install pandas, tabulate
# instead, pip install csv2md
...
from csv2md.table import Table
...
with open(src, encoding="utf-8") as f:
    table = Table.parse_csv(f)
md_table = table.markdown() # (1)
return markdown.markdown(md_table, extensions=["tables"])
    1. You can set the alignment parameters here.

  5. To build the mkdocs, must use python -m mkdocs build instead of mkdocs build. Otherwise, the local tools module will not be loaded.

  6. Demo:

    I saved a test csv file at: https://github.com/copdips/copdips.github.io/blob/main/docs/assets/blog_data/test.csv

    I referenced the csv file in Markdown file as below:

    ```csv-path
./docs/assets/blog_data/test.csv
```

    Then it was rendered like follows:

    name age
    aa 11
    bb 22

Comments