Registry /
web-framework / mkdocs-table-reader-plugin
Install & Compatibility
Where this runs
tested against v3.1.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 179.2MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 9.0s · import 0.000s · 173MB
180MB installed
● package 180MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
table-reader
✓ plugins:
- table-reader:
✗ import mkdocs_table_reader_plugin
MkDocs plugins are enabled by listing them in the `plugins` section of your `mkdocs.yml` configuration file, not by direct Python import in code.
This quickstart demonstrates how to enable the `mkdocs-table-reader-plugin` in your `mkdocs.yml` and use the `read_csv` macro to embed a table from a CSV file into your Markdown documentation. Create a `mkdocs.yml` file, a sample CSV file in `docs/data/`, and a Markdown file (`docs/index.md`) with the `{{ read_csv(...) }}` tag.
mkdocs.yml:
```yaml
site_name: My Data Docs
plugins:
- search
- table-reader
# Optional: Configure data_path if all your tables are in one directory
# plugins:
# - table-reader:
# data_path: assets/tables
```
docs/data/my_table.csv:
```csv
Header1,Header2
Value1,ValueA
Value2,ValueB
```
docs/index.md:
```markdown
# My Report
Here is some data from a CSV file:
{{ read_csv('data/my_table.csv') }}
And another one, specifying pandas options:
{{ read_csv('data/my_table.csv', sep=',', header=0) }}
```
Debug
Known issues
breakingThe `base_path` option for configuring the plugin was deprecated in v3.0.0. The plugin now searches for data files relative to `mkdocs.yml`, the `docs/` directory, and the current Markdown page's directory by default.fixRemove the `base_path` option from your `mkdocs.yml`. If you need to specify a default directory, use the `data_path` option instead, which configures a default path to be searched.
affects: >=3.0.0
breakingSupport for Python 3.7 was dropped in version 2.1.0.fixEnsure your project uses Python 3.8 or newer. If you must use Python 3.7, pin the plugin version to `<2.1.0` (e.g., `mkdocs-table-reader-plugin<2.1.0`).
affects: >=2.1.0
gotchaWhen using `mkdocs-table-reader-plugin` alongside `mkdocs-macros-plugin` or `mkdocs-markdownextradata-plugin`, the order of plugins in `mkdocs.yml` is crucial to prevent `UndefinedError` or incorrect rendering. `table-reader` should generally be listed *after* `macros` and `markdownextradata-plugin`.fixEnsure your `mkdocs.yml` lists plugins in the correct order, for example: `plugins: - search - macros - table-reader`. If you're using `mkdocs-macros-plugin` with indented content (like Admonitions or Content tabs), use the `| add_indentation(spaces=X)` filter provided by `table-reader`.
affects: All versions
gotchaSpecific Pandas versions might cause issues with internal DataFrame methods. For example, some users experienced regressions related to `df.map` or `applymap` on older Pandas versions.fixEnsure your `pandas` installation is up-to-date, preferably `pandas >= 2.1.0`, to avoid potential incompatibilities with the plugin's internal data handling.
affects: <2.0.2, <2.1.0 (for df.map)
gotchaAttempting to read modern `.xlsx` Excel files might result in an `XLRDError` if `openpyxl` is not installed.fixInstall the `openpyxl` library: `pip install openpyxl`.
affects: All versions
Upgrade
Version history
3.1.0latest on PyPI · released Aug 29, 2024
Audit
Dependencies
pandasrequiredRequired for reading various table formats like CSV, Excel, JSON, etc., as the plugin uses `pandas.read_*` functions internally.
openpyxloptionalRequired for reading `.xlsx` Excel files, as the older `xlrd` library does not support this format.
mkdocs-macros-pluginoptionalOptional, enables dynamic table insertion using Jinja2 syntax within Markdown files and provides additional `pd_<reader_name>` macros for advanced filtering and automation.