mkdocs-table-reader-plugin

What it is and what it does

mkdocs-table-reader-plugin extends MkDocs with a template tag system that reads tabular data from external files and renders them as markdown tables inline. Instead of manually copying table content into your documentation, you reference the file directly—the plugin handles parsing CSV, JSON, Excel, YAML, TSV, and other formats, then inserts the rendered table into the page at build time.

The plugin depends on mkdocs, pandas, tabulate, and PyYAML to handle file reading and formatting. It integrates with MkDocs' plugin system and is compatible with mkdocs-macros-plugin for more advanced automation like filtering or batch-inserting directories of tables. The workflow is useful for keeping documentation synchronized with live data files or for building reproducible reports where tables update automatically when source files change.

Use it for:

• Keep documentation tables synchronized with CSV or Excel source files without manual copy-paste
• Build reproducible reports where tables update automatically when underlying data files change
• Insert multiple tables from different file formats into a single MkDocs page using template tags
• Combine with mkdocs-macros-plugin to filter or transform tables before rendering them in documentation
• Generate data-driven documentation where tables are sourced from JSON or YAML configuration files

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

A MkDocs plugin that inserts tables from external files (CSV, JSON, Excel, YAML, and others) directly into markdown pages using template tags like `{{ read_csv('table.csv') }}`.

Yes, if you maintain MkDocs documentation that references external data files and want to keep tables synchronized automatically. The low install friction and permissive license make it a straightforward addition. However, note the aging maintenance status (715 days since last release)—suitable for stable workflows but not for projects requiring active upstream support or frequent updates to MkDocs compatibility.

Install

mkdocs-table-reader-plugin on PyPI

pip install mkdocs-table-reader-plugin

uv add mkdocs-table-reader-plugin

poetry add mkdocs-table-reader-plugin

Installing mkdocs-table-reader-plugin

Before you install

Low install friction; pure Python wheel with straightforward dependencies. Maintenance status is aging—last release was 715 days ago, though the repository remains active with a recent commit on 2025-04-19. Suitable for stable documentation workflows but not under active development.

License in practice

MIT license (permissive) means you can use, modify, and distribute this plugin freely in both open and closed projects with minimal restrictions.

Quickstart

pip install mkdocs-table-reader-plugin

Add to mkdocs.yml:
plugins:
  - search
  - table-reader

In markdown:
{{ read_csv('path_to_table.csv') }}

Requires MkDocs to be installed and configured; file paths are resolved relative to mkdocs.yml, docs/ directory, or the markdown source file.

Verify before relying

• Whether all advertised table formats (feather, fwf, etc.) are equally well-tested given the aging maintenance status
• Performance characteristics when reading large table files or many tables in a single build
• Compatibility with recent MkDocs versions beyond what the classifiers declare

Package facts

Evidence: mkdocs_table_reader_plugin-3.1.0-py3-none-any.whl

Keywords: mkdocs, plugin

Tags

More Documentation packages