From 47ac5d555176f114aa3edbf598b505633e3d2929 Mon Sep 17 00:00:00 2001
From: Tim Vink <vinktim@gmail.com>
Date: Mon, 26 Aug 2024 14:20:18 +0000
Subject: [PATCH] update docs on how to use jinja, see #72

---
 docs/howto/preprocess_tables.md |  4 +++
 docs/howto/use_jinja2.md        | 48 ++++++++++++++++++++++++++++++---
 2 files changed, 48 insertions(+), 4 deletions(-)

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