MkDocs Table Reader Plugin

Common errors

• jinja2.exceptions.UndefinedError: 'read_csv' is undefined

  cause The `table-reader` plugin is not correctly enabled in `mkdocs.yml`, or another plugin (like `mkdocs-markdownextradata-plugin` or `mkdocs-macros-plugin`) is processing Jinja2 tags before `table-reader` has a chance to register its macros, leading to conflicts.
  fix Verify that `plugins: - table-reader:` is present and correctly indented in your `mkdocs.yml`. If using with `mkdocs-macros-plugin` or `mkdocs-markdownextradata-plugin`, ensure `table-reader` is listed *after* them, e.g., `plugins: - macros - table-reader`.

• FileNotFoundError: [Errno 2] No such file or directory: 'your_table.csv'

  cause The specified path to the table data file is incorrect, or the file does not exist in any of the plugin's default search locations (project root, `docs/` directory, or the current Markdown page's directory).
  fix Double-check the file path in your `{{ read_...() }}` tag. Ensure it's correct relative to `mkdocs.yml`, your `docs/` directory, or the current Markdown file. You can also configure a `data_path` option in `mkdocs.yml` if all your tables reside in a common subdirectory, or use `allow_missing_files: true` during development to convert errors into warnings.

• XLRDError: Excel xlsx file; not supported by xlrd

  cause You are attempting to read an `.xlsx` Excel file, but the necessary `openpyxl` library is not installed. The `xlrd` library, which might be present, does not support this file format.
  fix Install `openpyxl` using pip: `pip install openpyxl`.

• Poetry add mkdocs-table-reader-plugin hangs when resolving dependencies

  cause This often occurs due to a Python version mismatch. Recent versions of `mkdocs-table-reader-plugin` and its `pandas` dependency require Python 3.8 or higher.
  fix Ensure your Python environment meets the `requires_python>=3.8` requirement. Upgrade your Python version or create a new virtual environment with Python 3.8 or newer.

Warnings

• breaking The `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.
  Fix: Remove 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.
• breaking Support for Python 3.7 was dropped in version 2.1.0.
  Fix: Ensure 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`).
• gotcha When 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`.
  Fix: Ensure 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`.
• gotcha Specific 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.
  Fix: Ensure your `pandas` installation is up-to-date, preferably `pandas >= 2.1.0`, to avoid potential incompatibilities with the plugin's internal data handling.
• gotcha Attempting to read modern `.xlsx` Excel files might result in an `XLRDError` if `openpyxl` is not installed.
  Fix: Install the `openpyxl` library: `pip install openpyxl`.

Install

• pip install mkdocs-table-reader-plugin Install stable version

Imports

• table-reader
  wrong:

  import mkdocs_table_reader_plugin

  correct:

  plugins:
    - table-reader:

  MkDocs plugins are enabled by listing them in the `plugins` section of your `mkdocs.yml` configuration file, not by direct Python import in code.

Quickstart

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

```