Skip to content

Readers

Basic readers

The following table reader functions are available:

read_csv

Use {{ read_csv() }} to read a comma-separated values (csv) and output as a markdown table.

  1. Arguments are parsed safely and then passed to corresponding functions below
  2. File is read using pandas.read_csv()
  3. The pd.DataFrame is then converted to a markdown table using .to_markdown()
  4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when not used with mkdocs-macros-plugin. See compatibility with macros plugin)

Example:

{{ read_csv('assets/tables/basic_table.csv') }}
a b
40 73
50 52
531456.123 80
name table1

Multiline cells

A markdown table row has to fit on a single line, so newlines inside a cell are replaced with <br>. Note that such a cell needs to be quoted to be valid CSV:

id,description
23456,"Some description.

With a line break."

read_fwf

Use {{ read_fwf() }} to read a table of fixed-width formatted lines and output as a markdown table.

  1. Arguments are parsed safely and then passed to corresponding functions below
  2. File is read using pandas.read_fwf()
  3. The pd.DataFrame is then converted to a markdown table using .to_markdown()
  4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when not used with mkdocs-macros-plugin. See compatibility with macros plugin)

Example:

{{ read_fwf('assets/tables/fixedwidth_table.txt') }}
Brand Price
Honda Civic 22001
Toyota Corolla 25000
Ford Focus 27000
Audi A4 35000

read_yaml

Use {{ read_yaml() }} to read a YAML file and output as a markdown table.

  1. Arguments are parsed safely and then passed to corresponding functions below
  2. File is read using yaml.safe_load() and then passed to pandas.json_normalize()
  3. The pd.DataFrame is then converted to a markdown table using .to_markdown()
  4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when not used with mkdocs-macros-plugin. See compatibility with macros plugin)

Example:

{{ read_yaml('assets/tables/yaml_table.yml') }}
a b
40 73
50 52
531456 80
name table1

The file is read as UTF-8. Use the encoding argument for files in another encoding, for example {{ read_yaml('assets/tables/yaml_table.yml', encoding='cp1251') }}.

read_table

Use {{ read_table() }} to read a general delimited file and output as a markdown table.

  1. Arguments are parsed safely and then passed to corresponding functions below
  2. File is read using pandas.read_table()
  3. The pd.DataFrame is then converted to a markdown table using .to_markdown()
  4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when not used with mkdocs-macros-plugin. See compatibility with macros plugin)

Example:

{{ read_table('assets/tables/basic_table.csv', sep = ',') }}
a b
40 73
50 52
531456.123 80
name table1

read_json

Use {{ read_json() }} to read a JSON string path and output as a markdown table.

  1. Arguments are parsed safely and then passed to corresponding functions below
  2. File is read using pandas.read_json()
  3. The pd.DataFrame is then converted to a markdown table using .to_markdown()
  4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when not used with mkdocs-macros-plugin. See compatibility with macros plugin)

Example:

{{ read_json('assets/tables/data.json', orient='split') }}
col 1 col 2
a b
c d

read_feather

Use {{ read_feather() }} to read a feather-format object and output as a markdown table.

  1. Arguments are parsed safely and then passed to corresponding functions below
  2. File is read using pandas.read_feather()
  3. The pd.DataFrame is then converted to a markdown table using .to_markdown()
  4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when not used with mkdocs-macros-plugin. See compatibility with macros plugin)

Example:

{{ read_feather('assets/tables/data.feather') }}
col 1 col 2
a b
c d

read_excel

Use {{ read_excel() }} to read an Excel file and output as a markdown table.

  1. Arguments are parsed safely and then passed to corresponding functions below
  2. File is read using pandas.read_excel()
  3. The pd.DataFrame is then converted to a markdown table using .to_markdown()
  4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when not used with mkdocs-macros-plugin. See compatibility with macros plugin)

Example:

{{ read_excel('assets/tables/excel_table.xlsx', engine='openpyxl') }}
a b
40 73
50 52
531456 8

Reading xlsx files

You might get a XLRDError('Excel xlsx file; not supported',) error when trying to read modern excel files. That's because xlrd does not support .xlsx files (stackoverflow post). Instead, install openpyxl and use:

{{ read_excel('assets/tables/excel_table.xlsx', engine='openpyxl') }}

read_parquet

Use {{ read_parquet() }} to read a parquet file and output as a markdown table.

  1. Arguments are parsed safely and then passed to corresponding functions below
  2. File is read using pandas.read_parquet()
  3. The pd.DataFrame is then converted to a markdown table using .to_markdown()
  4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when not used with mkdocs-macros-plugin. See compatibility with macros plugin)

Example:

{{ read_parquet('assets/tables/data.parquet') }}
product price
bread 1.25
milk 0.99
cheese 4.5

Requires pyarrow or fastparquet to be installed.

read_orc

Use {{ read_orc() }} to read an ORC object and output as a markdown table.

  1. Arguments are parsed safely and then passed to corresponding functions below
  2. File is read using pandas.read_orc()
  3. The pd.DataFrame is then converted to a markdown table using .to_markdown()
  4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when not used with mkdocs-macros-plugin. See compatibility with macros plugin)

Example:

{{ read_orc('assets/tables/data.orc') }}
product price
bread 1.25
milk 0.99
cheese 4.5

Requires pyarrow to be installed. On windows, pandas.read_orc() also needs the IANA time zone database to be available to pyarrow.

read_xml

Use {{ read_xml() }} to read an XML document and output as a markdown table.

  1. Arguments are parsed safely and then passed to corresponding functions below
  2. File is read using pandas.read_xml()
  3. The pd.DataFrame is then converted to a markdown table using .to_markdown()
  4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when not used with mkdocs-macros-plugin. See compatibility with macros plugin)

Example:

{{ read_xml('assets/tables/data.xml') }}
product price
bread 1.25
milk 0.99
cheese 4.5

Requires lxml to be installed, or use the standard library parser with {{ read_xml('assets/tables/data.xml', parser='etree') }}.

read_html

Use {{ read_html() }} to read the first table in an HTML document and output as a markdown table.

  1. Arguments are parsed safely and then passed to corresponding functions below
  2. File is read using pandas.read_html()
  3. The pd.DataFrame is then converted to a markdown table using .to_markdown()
  4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when not used with mkdocs-macros-plugin. See compatibility with macros plugin)

Example:

{{ read_html('assets/tables/data.html') }}
product price
bread 1.25
milk 0.99
cheese 4.5

pandas.read_html() returns every table it finds, so the first one is inserted. Use the match argument to select another table, for example {{ read_html('assets/tables/data.html', match='price') }}. Requires lxml, or beautifulsoup4 and html5lib, to be installed.

read_stata

Use {{ read_stata() }} to read a Stata file and output as a markdown table.

  1. Arguments are parsed safely and then passed to corresponding functions below
  2. File is read using pandas.read_stata()
  3. The pd.DataFrame is then converted to a markdown table using .to_markdown()
  4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when not used with mkdocs-macros-plugin. See compatibility with macros plugin)

Example:

{{ read_stata('assets/tables/data.dta') }}
product price
bread 1.25
milk 0.99
cheese 4.5

read_sas

Use {{ read_sas() }} to read a SAS file (XPORT or SAS7BDAT) and output as a markdown table.

  1. Arguments are parsed safely and then passed to corresponding functions below
  2. File is read using pandas.read_sas()
  3. The pd.DataFrame is then converted to a markdown table using .to_markdown()
  4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when not used with mkdocs-macros-plugin. See compatibility with macros plugin)

Example:

{{ read_sas('assets/tables/data.xpt', encoding='utf-8') }}
product price
bread 1.25
milk 0.99
cheese 4.5

Text columns are read as bytes unless you specify the encoding to decode them with.

read_spss

Use {{ read_spss() }} to read an SPSS file and output as a markdown table.

  1. Arguments are parsed safely and then passed to corresponding functions below
  2. File is read using pandas.read_spss()
  3. The pd.DataFrame is then converted to a markdown table using .to_markdown()
  4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when not used with mkdocs-macros-plugin. See compatibility with macros plugin)

Example:

{{ read_spss('assets/tables/data.sav') }}

Requires pyreadstat to be installed.

read_hdf

Use {{ read_hdf() }} to read an object stored in a HDF5 file and output as a markdown table.

  1. Arguments are parsed safely and then passed to corresponding functions below
  2. File is read using pandas.read_hdf()
  3. The pd.DataFrame is then converted to a markdown table using .to_markdown()
  4. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when not used with mkdocs-macros-plugin. See compatibility with macros plugin)

Example:

{{ read_hdf('assets/tables/data.h5', key='table') }}

Requires pytables to be installed. Specify the key of the object to read when the file contains more than one.

read_raw

Use {{ read_raw() }} to insert the contents from a file directly.

This is great if you have a file with a table already in markdown format. It could also replace a workflow where you use the snippets extension to embed external files.

  1. Only the first argument is read. This should be the file path.
  2. File is read using python
  3. The markdown table is fixed to match the indentation used by the tag in the markdown document (only when not used with mkdocs-macros-plugin. See compatibility with macros plugin)

Example:

{{ read_raw('assets/tables/markdown_table.md') }}
Tables Are Cool
col 1 is left-aligned $1600
col 2 is centered $12
col 3 is right-aligned $1

The file is read as UTF-8. Use the encoding argument for files in another encoding, for example {{ read_raw('assets/tables/markdown_table.md', encoding='cp1251') }}.

Macros

When you use table-reader with mkdocs-macros-plugin, in next to all the readers, the following additional macros will be made available:

pd_read_csv

Use {{ pd_read_csv() }} to read a comma-separated values (csv) using pandas.read_csv().

{{ pd_read_csv('assets/tables/basic_table.csv').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
a b
40 73
50 52
531456.123 80
name table1

pd_read_fwf

Use {{ pd_read_fwf() }} to read a table of fixed-width formatted lines using pandas.read_fwf()

Example:

{{ pd_read_fwf('assets/tables/fixedwidth_table.txt').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
Brand Price
Honda Civic 22001
Toyota Corolla 25000
Ford Focus 27000
Audi A4 35000

pd_read_yaml

Use {{ pd_read_yaml() }} to read a YAML file using yaml.safe_load() and pandas.json_normalize().

Example:

{{ pd_read_yaml('assets/tables/yaml_table.yml').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
a b
40 73
50 52
531456 80
name table1

The file is read as UTF-8. Use the encoding argument for files in another encoding, for example {{ pd_read_yaml('assets/tables/yaml_table.yml', encoding='cp1251') }}.

pd_read_table

Use {{ pd_read_table() }} to read a general delimited file using pandas.read_table().

Example:

{{ pd_read_table('assets/tables/basic_table.csv', sep = ',').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
a b
40 73
50 52
531456.123 80
name table1

pd_read_json

Use {{ pd_read_json() }} to read a JSON string path using pandas.read_json()

Example:

{{ pd_read_json('assets/tables/data.json', orient='split').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
col 1 col 2
a b
c d

pd_read_feather

Use {{ pd_read_feather() }} to read a feather-format object using pandas.read_feather()

Example:

{{ pd_read_feather('assets/tables/data.feather').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
col 1 col 2
a b
c d

pd_read_excel

Use {{ pd_read_excel() }} to read an Excel file using pandas.read_excel()

Example:

{{ pd_read_excel('assets/tables/excel_table.xlsx', engine='openpyxl').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
a b
40 73
50 52
531456 8

Reading xlsx files

You might get a XLRDError('Excel xlsx file; not supported',) error when trying to read modern excel files. That's because xlrd does not support .xlsx files (stackoverflow post). Instead, install openpyxl and use:

{{ pd_read_excel('assets/tables/excel_table.xlsx', engine='openpyxl') }}

pd_read_parquet

Use {{ pd_read_parquet() }} to read a parquet file using pandas.read_parquet()

Example:

{{ pd_read_parquet('assets/tables/data.parquet').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
product price
bread 1.25
milk 0.99
cheese 4.5

pd_read_orc

Use {{ pd_read_orc() }} to read an ORC object using pandas.read_orc()

Example:

{{ pd_read_orc('assets/tables/data.orc').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
product price
bread 1.25
milk 0.99
cheese 4.5

pd_read_xml

Use {{ pd_read_xml() }} to read an XML document using pandas.read_xml()

Example:

{{ pd_read_xml('assets/tables/data.xml').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
product price
bread 1.25
milk 0.99
cheese 4.5

pd_read_html

Use {{ pd_read_html() }} to read the first table in an HTML document using pandas.read_html()

Example:

{{ pd_read_html('assets/tables/data.html').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
product price
bread 1.25
milk 0.99
cheese 4.5

pd_read_stata

Use {{ pd_read_stata() }} to read a Stata file using pandas.read_stata()

Example:

{{ pd_read_stata('assets/tables/data.dta').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
product price
bread 1.25
milk 0.99
cheese 4.5

pd_read_sas

Use {{ pd_read_sas() }} to read a SAS file (XPORT or SAS7BDAT) using pandas.read_sas()

Example:

{{ pd_read_sas('assets/tables/data.xpt', encoding='utf-8').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}
product price
bread 1.25
milk 0.99
cheese 4.5

pd_read_spss

Use {{ pd_read_spss() }} to read an SPSS file using pandas.read_spss()

Example:

{{ pd_read_spss('assets/tables/data.sav').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}

pd_read_hdf

Use {{ pd_read_hdf() }} to read an object stored in a HDF5 file using pandas.read_hdf()

Example:

{{ pd_read_hdf('assets/tables/data.h5', key='table').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}

Filters

When you use table-reader with mkdocs-macros-plugin, in next to all the readers, the macros, the following additional filters will be made available:

add_indentation

Adds a consistent indentation to every line in a string. This is important when you are inserting content into Admonitions or Content tabs.

Args: text (str): input text spaces (int): Indentation to add in spaces tabs (int): Indentation to add in tabs

Example usage: 

!!! note "this is a note"
    {{ pd_read_csv('assets/tables/basic_table.csv').to_markdown(tablefmt="pipe", index=False) | add_indentation(spaces=4) }}

convert_to_md_table

Converts a pandas dataframe into a markdown table. Arguments are passed to .to_markdown(). By default, tablefmt='pipe' and index=False are used. There is also an additional fix to ensure any pipe (|) characters in the dataframe are properly escaped (python-tabulate#241).

Example usage: 

{{ pd_read_csv('assets/tables/basic_table.csv') | convert_to_md_table  }}
Authors: Tim Vink, Tim Vink, Tim Vink, bartvanwoesik