diff --git a/docs/howto/preprocess_tables.md b/docs/howto/preprocess_tables.md index 9fac1da..e1c2558 100644 --- a/docs/howto/preprocess_tables.md +++ b/docs/howto/preprocess_tables.md @@ -54,6 +54,10 @@ Here are some example of workflows that use hooks and the `table-reader` plugin: └── mkdocs.yml ``` +!!! note "Alternative: use jinja" + + You can also use jinja2 to display a list of tables. See how to [use jinja2 for automation](use_jinja2.md). + ## Download a table from an API === "hooks.py" diff --git a/docs/howto/use_jinja2.md b/docs/howto/use_jinja2.md index 182b936..8ab66f9 100644 --- a/docs/howto/use_jinja2.md +++ b/docs/howto/use_jinja2.md @@ -1,4 +1,4 @@ -# Using jinja2 +# Use jinja2 for automation `table-reader` supports [`mkdocs-macros-plugin`](https://mkdocs-macros-plugin.readthedocs.io/en/latest/), which enables you to use jinja2 syntax inside markdown files (among other things). @@ -10,8 +10,9 @@ plugins: - table-reader ``` -Now you can do cool things like dynamically load a list of tables: +Now you can do cool things like: +## Dynamically load a list of tables ```markdown # index.md @@ -22,10 +23,9 @@ Now you can do cool things like dynamically load a list of tables: { { read_csv(table_name) }} {% endfor %} - ``` -## Indented content like content tabs +## Insert tables into content tabs If you inserted content has multiple lines, then indentation will be not be retained beyond the first line. This means things like [content tabs](https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#usage) will not work as expected. @@ -69,3 +69,43 @@ To fix that, you can use the custom _filter_ `add_indendation` (a filter add to To avoid the tables being inserted into the code example, we replaced `{{` with `{ {`. If you copy this example, make sure to fix. + +## Recursively insert an entire directory of tables + +[`mkdocs-macros-plugin`](https://mkdocs-macros-plugin.readthedocs.io/en/latest/) 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: + +```python +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: + +```markdown +# index.md + +{% for table_name in listdir('docs/assets/my_tables") %} + +{ { read_csv(table_name) }} + +{% endfor %} +``` + +!!! note "Note the space in { {" + + To avoid the tables being inserted into the code example, we replaced `{{` with `{ {`. + If you copy this example, make sure to fix. \ No newline at end of file