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:

InputOutput

{{ read_csv('assets/tables/basic_table.csv') }}

a	b
40	73
50	52
531456.123	80
name	table1

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:

InputOutput

{{ 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:

InputOutput

{{ read_yaml('assets/tables/yaml_table.yml') }}

a	b
40	73
50	52
531456	80
name	table1

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:

InputOutput

{{ 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:

InputOutput

{{ 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:

InputOutput

{{ 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:

InputOutput

{{ 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_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:

InputOutput

{{ 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

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().

InputOutput

{{ 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:

InputOutput

{{ 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:

InputOutput

{{ 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

pd_read_table

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

Example:

InputOutput

{{ 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:

InputOutput

{{ 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:

InputOutput

{{ 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:

InputOutput

{{ 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') }}

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, bartvanwoesik