---
id: mkdocs-table-reader-plugin
version: "3.1.0"
license: MIT
license_treatment: permissive
maintenance: aging
---

# mkdocs-table-reader-plugin — MkDocs plugin to directly insert tables from files into markdown.

License: permissive · Maintenance: aging · Downloads: 234.4K/mo

## 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 above — 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

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

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 234.4K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

mkdocs table insertion plugin, embed csv in markdown, read external tables mkdocs, markdown table from file, mkdocs data file reader, dynamic table generation markdown, csv to markdown plugin, mkdocs-plugin, data-driven-docs, table-embedding

[View on SkillFed](https://skillfed.io/packages/mkdocs-table-reader-plugin) · [View on PyPI](https://pypi.org/project/mkdocs-table-reader-plugin/)