Compatibility with mkdocs-macros-plugin to enable further automation

table-reader supports mkdocs-macros-plugin, which enables you to use jinja2 syntax inside markdown files (among other things).

To enable macros, specify the plugin before table-reader in your mkdocs.yml file:

plugins:
    - macros
    - table-reader

Everything will work as before, except indentation will not be retrained. This means components that rely on indentation (like Admonitions and Content tabs) will break.

The solution is to use the custom filter add_indendation (a filter added to macros by table-reader plugin, see the readers). For example:

!!! note "This is a note"

    {{ read_csv("basic_table.csv") | add_indentation(spaces=4) }}

The upside is you now have much more control. A couple of example use cases:

Dynamically load a specified list of tables into tabs

index.mdmkdocs.yml

{% set table_names = ["basic_table.csv","basic_table2.csv"] %}
{% for table_name in table_names %}

=== "{{ table_name }}"

    {{ read_csv(table_name) | add_indentation(spaces=4) }}

{% endfor %}

site_name: test git_table_reader site
use_directory_urls: true

theme:
name: material

plugins:
    - search
    - macros
    - table-reader

markdown_extensions:
    - pymdownx.superfences
    - pymdownx.tabbed:
        alternate_style: true

Recursively insert an entire directory of tables

mkdocs-macros-plugin enables you to define additional functions (called macros) that you will be able to use within your markdown files. See their documentation on how to set this up. Here's an example with some functions to interact with the filesystem:

def define_env(env):
    """
    Register additional mkdocs-macros-plugin functions that can be used as macros in markdown files.
    """    
    @env.macro
    def listdir(path):
        return os.listdir(path)

    @env.macro
    def path_exists(path):
        return Path(path).exists()

    @env.macro
    def is_file(path):
        return Path(path).is_file() 

Now you could do something like:

# index.md

{% for table_name in listdir('docs/assets/my_tables") %}

{{ read_csv(table_name) }}

{% endfor %}

Filter a table before inserting it

When you enable the macros plugin in your mkdocs.yml, table-reader will add additional macros and filters (see the readers overview).

You can use the pd_<reader> variants to read a file to a pandas dataframe. Then you can use the pandas methods like .query(). For example:

{{ pd_read_csv("numeric_table.csv").query("column_name >= 3") | convert_to_md_table }}

Authors: Tim Vink