@timvink I am the developer of Mkdocs-Macros. I am contacting you since I noticed that you have given thought to the production of reproducible reports.

I noticed that several MkDocs plugins operate with the idea of using a "macro" style notation inside a Markdown page, e.g.:

{{ read_csv('cities.csv')}}

So my idea was to put together a generalized plugin that would provide a powerful reference syntax (Jinja2), as well as all the boilerplate (template engine, error management, etc., while leaving some flexibility). The developer would only have to focus on developing the Python functions (which would then become macros within the Markdown page). It works and the plugin is used by many Mkdocs projects (more than 2'500, according to Github).

To facilitate that migration effort, I implemented the concept of pluglets, which are installable as any Python package. Basically, any plugin that uses the concept of macros (like this table reader) could be rewritten by their author. But of course, that would be a matter of time, effort versus return on investment, etc.

However, there is a "transient" issue because Mkdocs-Macros and the other existing plugins that use a similar syntax might interfere with each other (depending on in which order they are declared and so on). This is a question that comes up a lot.

So, in the mean time, what if we used the code of an existing plugin in Mkdocs Macros?

To get an idea of how this idea could work in practice, I tried the experiment of writing a module that would import the applicable code of mkdocs-table-reader-plugin. It was very straightforward.

Here is the minimal code for a module (main.py in the root directory of the MkDocs project):

from mkdocs_table_reader_plugin.readers import *

def define_env(env):
    """
    This is the hook for the functions (new form)
    """
    for reader in READERS.values():
        env.macro(reader)

It does the following: it lists all the readers, which are conveniently listed in READERS (['read_csv', 'read_table', 'read_fwf', 'read_excel', 'read_yaml', 'read_json', 'read_feather', 'read_raw']) and declares them as macros. And voilà they were imported as macros available in every markdown page! Now its even possible to add programming logic (for repetitive actions), etc..

I attached the whole Mkdocs test project (mkdocs-tables-module.zip), so that you could reproduce my experiment, if you wish. It only requires a pip-install mkdocs-macros-plugin.

I just wished to know what you think about it, and if there could be potentially workable ideas there?