README.md

mkdocs-table-reader-plugin

MkDocs plugin that enables a markdown tag like {{ read_csv('table.csv') }} to directly insert various table formats into a page.

For a workflow with other plugins see the blogpost building reproducible reports with MkDocs

Installation

Install the plugin using pip:

pip install mkdocs-table-reader-plugin

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

plugins:
  - 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.

Usage

In your markdown files 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, or your project's docs/ directory, or the location of your markdown source file (all 3 possible locations will be searched, in that order).

• There are readers available for many common table formats, like .csv, .fwf, .json, .xls, .xlsx, .yaml, .feather and .tsv. There is also the read_raw() reader that will allow you to insert tables (or other content) already in markdown format.
• table-reader is compatible with mkdocs-macros-plugin. This enables further automation like filtering tables or inserting directories of tables. See the documentation on compatibility with macros plugin for more examples.

Documentation and how-to guides

See timvink.github.io/mkdocs-table-reader-plugin/