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. -
In
mkdocs.yml
, add custom fence forcsv-path
language: -
Install additional pip dependencies:
-
In
tools/pymdownx_md_render.py
, add a new functionmd_csv_path_render()
to handle csv code block. Check here to see apymdownx_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 ofmkdocs build
. Otherwise, the localtools
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:
Then it was rendered like follows:
name age aa 11 bb 22