{"id":8323,"library":"mkdocs-table-reader-plugin","title":"MkDocs Table Reader Plugin","description":"mkdocs-table-reader-plugin is an MkDocs plugin designed to directly insert tables from various file formats (like CSV, Excel, JSON, YAML, Feather) into Markdown documentation. It is currently at version 3.1.0 and is actively maintained with regular updates and improvements.","status":"active","version":"3.1.0","language":"en","source_language":"en","source_url":"https://github.com/timvink/mkdocs-table-reader-plugin","tags":["mkdocs","plugin","documentation","table","csv","excel","json","yaml","data"],"install":[{"cmd":"pip install mkdocs-table-reader-plugin","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for reading various table formats like CSV, Excel, JSON, etc., as the plugin uses `pandas.read_*` functions internally.","package":"pandas","optional":false},{"reason":"Required for reading `.xlsx` Excel files, as the older `xlrd` library does not support this format.","package":"openpyxl","optional":true},{"reason":"Optional, enables dynamic table insertion using Jinja2 syntax within Markdown files and provides additional `pd_<reader_name>` macros for advanced filtering and automation.","package":"mkdocs-macros-plugin","optional":true}],"imports":[{"note":"MkDocs plugins are enabled by listing them in the `plugins` section of your `mkdocs.yml` configuration file, not by direct Python import in code.","wrong":"import mkdocs_table_reader_plugin","symbol":"table-reader","correct":"plugins:\n  - table-reader:"}],"quickstart":{"code":"mkdocs.yml:\n```yaml\nsite_name: My Data Docs\nplugins:\n  - search\n  - table-reader\n\n# Optional: Configure data_path if all your tables are in one directory\n# plugins:\n#   - table-reader:\n#       data_path: assets/tables\n```\n\ndocs/data/my_table.csv:\n```csv\nHeader1,Header2\nValue1,ValueA\nValue2,ValueB\n```\n\ndocs/index.md:\n```markdown\n# My Report\n\nHere is some data from a CSV file:\n\n{{ read_csv('data/my_table.csv') }}\n\nAnd another one, specifying pandas options:\n\n{{ read_csv('data/my_table.csv', sep=',', header=0) }}\n\n```","lang":"yaml+markdown","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.0.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`).","message":"Support for Python 3.7 was dropped in version 2.1.0.","severity":"breaking","affected_versions":">=2.1.0"},{"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`.","message":"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`.","severity":"gotcha","affected_versions":"All 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.","message":"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.","severity":"gotcha","affected_versions":"<2.0.2, <2.1.0 (for df.map)"},{"fix":"Install the `openpyxl` library: `pip install openpyxl`.","message":"Attempting to read modern `.xlsx` Excel files might result in an `XLRDError` if `openpyxl` is not installed.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","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.","error":"jinja2.exceptions.UndefinedError: 'read_csv' is undefined"},{"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.","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).","error":"FileNotFoundError: [Errno 2] No such file or directory: 'your_table.csv'"},{"fix":"Install `openpyxl` using pip: `pip install openpyxl`.","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.","error":"XLRDError: Excel xlsx file; not supported by xlrd"},{"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.","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.","error":"Poetry add mkdocs-table-reader-plugin hangs when resolving dependencies"}]}