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<-- "". 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.

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

    - pymdownx.superfences:
        - 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/, add a new function md_csv_path_render() to handle csv code block. Check here to see a example.

    tablefmt="github" is to set the alignment.

    file tools/
    ... other imports
    import pandas as pd
    ... other functions
    def md_csv_path_render(
            options=None, md="",
        """Formatter wrapper."""
            df = pd.read_csv(src)
            return markdown.markdown(
                df.to_markdown(tablefmt="github", index=False),
        except Exception:
            import traceback

    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:

    I referenced the csv file in Markdown file as below:


    Then it was rendered like follows:

    name age
    aa 11
    bb 22