Options
You can customize the plugin by setting options in mkdocs.yml. For example:
plugins:
- table-reader:
data_path: "."
allow_missing_files: False
select_readers:
- read_csv
- read_json
enabled: True
data_path
Default is .. Set a default path to the searched directories in order to shorten table filename specifications.
Given a file path, table-reader will search for that file relative to your project's mkdocs.yml and relative to your docs/ folder. If you use a folder for all your table files you can shorten the path specification by setting the data_path.
For example, if your table is located in docs/assets/tables/basic_table.csv, you can set data_path to docs/assets/tables/. Then you will be able to use {{ read_csv("basic_table.csv") }} instead of {{ read_csv("docs/assets/tables/basic_table.csv") }} inside any markdown page.
Info
Note that by default the plugin will also search the page's directory but only when a table is not found.
For more examples see the how to guide on project structure.
allow_missing_files
Default: False. When enabled, if a filepath is not found, the plugin will raise a warning instead of an error.
select_readers
Default: Selects all available readers. Every page is searched for all selected readers in a single pass, so limiting the list saves little time; use it when you want to be sure only specific readers are used. This option is ignored when you use this plugin with mkdocs-macros-plugin (read more)
Note that some readers need an additional package to be installed, see readers.
enabled
Default is True. Enables you to deactivate this plugin. This option is supported by all plugins since mkdocs 1.6 (see docs). A possible use case is local development where you might want faster build times and/or do not have the tables ready. It's recommended to use this option with an environment variable together with a default fallback (introduced in mkdocs v1.2.1, see docs). Example:
plugins:
- table-reader:
enabled: !ENV [ENABLED_TABLE_READER, True]
Which enables you to disable the plugin locally using:
export ENABLED_TABLE_READER=false
mkdocs serve