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