Skip to main content

MkDocs plugin to directly insert tables from files into markdown.

Project description

Actions Status PyPI - Python Version PyPI PyPI - Downloads codecov GitHub contributors PyPI - License


MkDocs plugin that adds a {{ read_csv('table.csv') }} markdown tag to directly insert CSV files as a table into a page. See it in action at

This makes it easier to build reproducible reports. For more complex use cases, consider mknotebooks, mkdocs-markdownextradata-plugin or mkdocs-macros-plugin.


Install the plugin using pip3:

pip3 install mkdocs-table-reader-plugin

Next, add the following lines to your mkdocs.yml:

  - search
  - table-reader

If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set.


In your markdown documents you can now use:

{{ read_csv('path_to_table.csv') }}

Where the path is relative to the location of your project's mkdocs.yml file.

Under the hood this is basically:

import pandas as pd
df = pd.read_csv('path_to_table.csv')
df.to_markdown(index=False, tablefmt='pipe')

Which means you can pass all parameters of pandas.read_csv().

You can see an example usage in this repo (see mkdocs.yml and docs/) and the result at

Available readers

The following table reader functions are available:

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('tables/excel_table.xlsx', engine='openpyxl') }}

Reading yaml variables

mkdocs-markdownextradata-plugin is a great plugin to use when working with yaml files. It will read in all yaml files in a specified directory and make all keys available as jinja2 variables.


You can customize the plugin by setting options in mkdocs.yml. For example:

  - table-reader:
      data_path: "docs"


Default is ., which means you can specify the path to your table files relative to the location of your project's mkdocs.yml file. If you use a folder for all your table files you can shorten the path specification by setting data_path.

For example, if you set data_path to docs/ in the project below, you will be able to use {{ read_csv("basic_table.csv") }} instead of {{ read_csv("docs/basic_table.csv") }} inside

├── docs
│   ├── basic_table.csv
│   └──
└── mkdocs.yml


Contributions are very welcome! Please read before putting in any work.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for mkdocs-table-reader-plugin, version 0.5
Filename, size File type Python version Upload date Hashes
Filename, size mkdocs_table_reader_plugin-0.5-py3-none-any.whl (7.5 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size mkdocs-table-reader-plugin-0.5.tar.gz (5.9 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page