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.

In Markdown file, use code block with language csv to render CSV as Markdown table.
```
```csv-path
my_csv_file_path.csv
```
```

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

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

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"])

You can set the alignment parameters here.

To build the mkdocs, must use python -m mkdocs build instead of mkdocs build. Otherwise, the local tools module will not be loaded.
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

name	age
aa	11
bb	22

Rendering CSV as Markdown table in Mkdocs Material#

Comments