diff --git a/docs/howto/alternatives.md b/docs/howto/alternatives.md
index 4f7ad33..cec6bbf 100644
--- a/docs/howto/alternatives.md
+++ b/docs/howto/alternatives.md
@@ -39,7 +39,7 @@ Downsides:
## Execute python during build
-You could also choose to insert the markdown for tables dynamically, using packages like [markdown-exec]() or [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/).
+You could also choose to insert the markdown for tables dynamically, using packages like [markdown-exec](https://pypi.org/project/markdown-exec/).
For example:
diff --git a/docs/howto/customize_tables.md b/docs/howto/customize_tables.md
index 02dac1c..66c1312 100644
--- a/docs/howto/customize_tables.md
+++ b/docs/howto/customize_tables.md
@@ -12,8 +12,10 @@ df = pd.read_csv('path_to_table.csv')
df.to_markdown(index=False, tablefmt='pipe')
```
-Any keyword arguments you give to \{\{ read_csv('path_to_your_table.csv') \}\}
will be matched and passed the corresponding [pandas.read_csv()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_csv.html) and/or
+{% raw %}
+Any keyword arguments you give to `{{ read_csv('path_to_your_table.csv') }}` will be matched and passed the corresponding [pandas.read_csv()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_csv.html) and/or
[.to_markdown()](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_markdown.html) functions.
+{% endraw %}
Pandas's `.to_markdown()` uses the [tabulate](https://pypi.org/project/tabulate/) package and any keyword arguments that are passed to it. Tabulate in turn offers many customization options, see [library usage](https://github.com/astanin/python-tabulate#library-usage).
@@ -23,21 +25,33 @@ Text columns will be aligned to the left [by default](https://github.com/astanin
=== ":arrow_left: left"
- \{\{ read_csv('tables/basic_table.csv', colalign=("left",)) \}\}
-
+ {% raw %}
+ ```
{{ read_csv('tables/basic_table.csv', colalign=("left",)) }}
+ ```
+ {% endraw %}
-=== ":left_right_arrow: center"
+ {{ read_csv('tables/basic_table.csv', colalign=("left",)) | add_indentation(spaces=4) }}
- \{\{ read_csv('tables/basic_table.csv', colalign=("center",)) \}\}
+=== ":left_right_arrow: center"
+ {% raw %}
+ ```
{{ read_csv('tables/basic_table.csv', colalign=("center",)) }}
+ ```
+ {% endraw %}
-=== ":arrow_right: right"
+ {{ read_csv('tables/basic_table.csv', colalign=("center",)) | add_indentation(spaces=4) }}
- \{\{ read_csv('tables/basic_table.csv', colalign=("right",)) \}\}
+=== ":arrow_right: right"
+ {% raw %}
+ ```
{{ read_csv('tables/basic_table.csv', colalign=("right",)) }}
+ ```
+ {% endraw %}
+
+ {{ read_csv('tables/basic_table.csv', colalign=("right",)) | add_indentation(spaces=4) }}
## Sortable tables
@@ -47,21 +61,33 @@ If you use [mkdocs-material](https://squidfunk.github.io/mkdocs-material), you c
You can use [tabulate](https://pypi.org/project/tabulate/)'s [number formatting](https://github.com/astanin/python-tabulate#number-formatting). Example:
-=== ":zero:"
-
- \{\{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".0f") \}\}
+=== "zero points"
+ {% raw %}
+ ```
{{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".0f") }}
+ ```
+ {% endraw %}
-=== ":one:"
+ {{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".0f") | add_indentation(spaces=4) }}
- \{\{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".1f") \}\}
+=== "one points"
+ {% raw %}
+ ```
{{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".1f") }}
+ ```
+ {% endraw %}
-=== ":two:"
+ {{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".1f") | add_indentation(spaces=4) }}
- \{\{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".2f") \}\}
+=== "two points"
+ {% raw %}
+ ```
{{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".2f") }}
+ ```
+ {% endraw %}
+
+ {{ read_fwf('tables/fixedwidth_table.txt', floatfmt=".2f") | add_indentation(spaces=4) }}
diff --git a/docs/howto/preprocess_tables.md b/docs/howto/preprocess_tables.md
index e1c2558..a150e35 100644
--- a/docs/howto/preprocess_tables.md
+++ b/docs/howto/preprocess_tables.md
@@ -1,5 +1,7 @@
# Preprocess input tables
+{% raw %}
+
`mkdocs>=1.4` supports [hooks](https://www.mkdocs.org/user-guide/configuration/#hooks), which enable you to run python scripts on `mkdocs serve` or `mkdocs build`.
Here are some example of workflows that use hooks and the `table-reader` plugin:
@@ -26,7 +28,7 @@ Here are some example of workflows that use hooks and the `table-reader` plugin:
My table:
- \{\{ read_csv("docs/assets/output_table.csv") \}\}
+ {{ read_csv("docs/assets/output_table.csv") }}
=== "mkdocs.yml"
@@ -74,7 +76,7 @@ Here are some example of workflows that use hooks and the `table-reader` plugin:
My table:
- \{\{ read_csv("docs/assets/nyc_data.csv") \}\}
+ {{ read_csv("docs/assets/nyc_data.csv") }}
=== "mkdocs.yml"
@@ -101,3 +103,5 @@ Here are some example of workflows that use hooks and the `table-reader` plugin:
```
Note that during development when you use `mkdocs serve` and autoreload, you might not want to run this hook every time you make a change. You could use an environment variable inside your hook, for example something like `if os.environ['disable_hook'] == 1: return None`.
+
+{% endraw %}
\ No newline at end of file
diff --git a/docs/howto/project_structure.md b/docs/howto/project_structure.md
index 7ba2966..9243a18 100644
--- a/docs/howto/project_structure.md
+++ b/docs/howto/project_structure.md
@@ -1,4 +1,5 @@
# Choose a project structure
+{% raw %}
You have different possible strategies to store and load your tables. This guide gives some examples.
@@ -23,14 +24,14 @@ If you only want to include an occasional table in a specific markdown file, jus
```md
Here is the table:
- \{\{ read_csv("another_table.csv") \}\}
+ {{ read_csv("another_table.csv") }}
```
In `page.md`, to read `another_table.csv`, you can choose to use:
-- \{\{ read_csv("docs/folder/another_table.csv") \}\}
(Path relative to mkdocs.yml)
-- \{\{ read_csv("folder/another_table.csv") \}\}
(Path relative to docs/ directory)
-- \{\{ read_csv("another_table.csv") \}\}
(Path relative to page source file)
+- `{{ read_csv("docs/folder/another_table.csv") }}` (Path relative to mkdocs.yml)
+- `{{ read_csv("folder/another_table.csv") }}` (Path relative to docs/ directory)
+- `{{ read_csv("another_table.csv") }}` (Path relative to page source file)
## Re-using tables across markdown files
@@ -54,7 +55,8 @@ Given the following project structure:
In `page.md`, to read `another_table.csv`, you can choose to use:
-- \{\{ read_csv("docs/assets/tables/another_table.csv") \}\}
(Path relative to mkdocs.yml)
-- \{\{ read_csv("assets/tables/another_table.csv") \}\}
(Path relative to docs/ directory)
-- \{\{ read_csv("../assets/tables/another_table.csv") \}\}
(Path relative to page source file _(note that `..` stands for "one directory up")_)
+- `{{ read_csv("docs/assets/tables/another_table.csv") }}` (Path relative to mkdocs.yml)
+- `{{ read_csv("assets/tables/another_table.csv") }}` (Path relative to docs/ directory)
+- `{{ read_csv("../assets/tables/another_table.csv") }}` (Path relative to page source file _(note that `..` stands for "one directory up")_)
+{% endraw %}
\ No newline at end of file
diff --git a/docs/howto/use_jinja2.md b/docs/howto/use_jinja2.md
index 8ab66f9..02cbe8f 100644
--- a/docs/howto/use_jinja2.md
+++ b/docs/howto/use_jinja2.md
@@ -1,4 +1,5 @@
# Use jinja2 for automation
+{% raw %}
`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).
@@ -14,17 +15,19 @@ Now you can do cool things like:
## Dynamically load a list of tables
+
```markdown
# index.md
{% set table_names = ["basic_table.csv","basic_table2.csv"] %}
{% for table_name in table_names %}
-{ { read_csv(table_name) }}
+{{ read_csv(table_name) }}
{% endfor %}
```
+
## 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.
@@ -39,7 +42,7 @@ To fix that, you can use the custom _filter_ `add_indendation` (a filter add to
=== "{{ table_name }}"
- { { read_csv(table_name) | add_indentation(spaces=4) }}
+ {{ read_csv(table_name) | add_indentation(spaces=4) }}
{% endfor %}
```
@@ -64,10 +67,6 @@ To fix that, you can use the custom _filter_ `add_indendation` (a filter add to
alternate_style: true
```
-!!! 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.
## Recursively insert an entire directory of tables
@@ -100,12 +99,9 @@ Now you could do something like:
{% for table_name in listdir('docs/assets/my_tables") %}
-{ { read_csv(table_name) }}
+{{ 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
+{% endraw %}
\ No newline at end of file
diff --git a/docs/options.md b/docs/options.md
index ed5a5fe..52e19a5 100644
--- a/docs/options.md
+++ b/docs/options.md
@@ -4,6 +4,7 @@ hide:
---
# Options
+{% raw %}
You can customize the plugin by setting options in `mkdocs.yml`. For example:
@@ -24,7 +25,7 @@ Default is `.`. Set a default path to the searched directories in order to short
Given a file path, `table-reader` will search for that file relative to your your project's `mkdocs.yml` and relative to your `docs/` folder. If you use a folder for all your table files you can shorten the path specification by setting the `data_path`.
-For example, if your table is located in `docs/assets/tables/basic_table.csv`, you can set `data_path` to `docs/assets/tables/`. Then you will be able to use \{\{ read_csv("basic_table.csv") \}\}
instead of \{\{ read_csv("docs/assets/tables/basic_table.csv") \}\}
inside any markdown page.
+For example, if your table is located in `docs/assets/tables/basic_table.csv`, you can set `data_path` to `docs/assets/tables/`. Then you will be able to use `{{ read_csv("basic_table.csv") }}` instead of `{{ read_csv("docs/assets/tables/basic_table.csv") }}` inside any markdown page.
!!! info
@@ -57,4 +58,6 @@ Which enables you to disable the plugin locally using:
```bash
export ENABLED_TABLE_READER=false
mkdocs serve
-```
\ No newline at end of file
+```
+
+{% endraw %}
\ No newline at end of file
diff --git a/docs/readers.md b/docs/readers.md
index 5298fd6..11eb48f 100644
--- a/docs/readers.md
+++ b/docs/readers.md
@@ -9,112 +9,148 @@ The following table reader functions are available:
## read_csv
-`{{ read_csv() }}` passed to [pandas.read_csv()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_csv.html). Example:
+{% raw %}`{{ read_csv() }}`{% endraw %} passed to [pandas.read_csv()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_csv.html). Example:
=== "Input"
- \{\{ read_csv('tables/basic_table.csv') \}\}
+ {% raw %}
+ ```markdown
+ {{ read_csv('assets/tables/basic_table.csv') }}`
+ ```
+ {% endraw %}
=== "Output"
- {{ read_csv('tables/basic_table.csv') }}
+ {{ read_csv('assets/tables/basic_table.csv') | add_indentation(spaces=4) }}
## read_fwf
-`{{ read_fwf() }}` passed to [pandas.read_fwf()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_fwf.html). Example:
+{% raw %}`{{ read_fwf() }}`{% endraw %} passed to [pandas.read_fwf()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_fwf.html). Example:
=== "Input"
- \{\{ read_fwf('tables/fixedwidth_table.txt') \}\}
+ {% raw %}
+ ```markdown
+ {{ read_fwf('assets/tables/fixedwidth_table.txt') }}
+ ```
+ {% endraw %}
=== "Output"
- {{ read_fwf('tables/fixedwidth_table.txt') }}
+ {{ read_fwf('assets/tables/fixedwidth_table.txt') | add_indentation(spaces=4) }}
## read_yaml
-`{{ read_yaml() }}` is parsed with [yaml.safe_load()](https://pyyaml.org/wiki/PyYAMLDocumentation#loading-yaml) and passed to [pandas.json_normalize()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.json_normalize.html). Example:
+{% raw %}`{{ read_yaml() }}`{% endraw %} is parsed with [yaml.safe_load()](https://pyyaml.org/wiki/PyYAMLDocumentation#loading-yaml) and passed to [pandas.json_normalize()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.json_normalize.html). Example:
=== "Input"
- \{\{ read_yaml('tables/yaml_table.yml') \}\}
+ {% raw %}
+ ```markdown
+ {{ read_yaml('assets/tables/yaml_table.yml') }}
+ ```
+ {% endraw %}
=== "Output"
- {{ read_yaml('tables/yaml_table.yml') }}
+ {{ read_yaml('assets/tables/yaml_table.yml') | add_indentation(spaces=4) }}
## read_table
-`{{ read_table() }}` passed to [pandas.read_table()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_table.html). Example:
+{% raw %}`{{ read_table() }}`{% endraw %} passed to [pandas.read_table()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_table.html). Example:
=== "Input"
- \{\{ read_table('tables/basic_table.csv', sep = ',') \}\}
+ {% raw %}
+ ```markdown
+ {{ read_table('assets/tables/basic_table.csv', sep = ',') }}
+ ```
+ {% endraw %}
=== "Output"
- {{ read_table('tables/basic_table.csv', sep = ',') }}
+ {{ read_table('assets/tables/basic_table.csv', sep = ',') | add_indentation(spaces=4) }}
## read_json
-`{{ read_json() }}` passed to [pandas.read_json()](https://pandas.pydata.org/docs/reference/api/pandas.read_json.html). Example:
+{% raw %}`{{ read_json() }}`{% endraw %} passed to [pandas.read_json()](https://pandas.pydata.org/docs/reference/api/pandas.read_json.html). Example:
=== "Input"
- \{\{ read_json('tables/data.json', orient='split') \}\}
+ {% raw %}
+ ```markdown
+ {{ read_json('assets/tables/data.json', orient='split') }}
+ ```
+ {% endraw %}
=== "Output"
- {{ read_json('tables/data.json', orient='split') }}
+ {{ read_json('assets/tables/data.json', orient='split') | add_indentation(spaces=4) }}
## read_feather
-`{{ read_feather() }}` passed to [pandas.read_feather()](https://pandas.pydata.org/docs/reference/api/pandas.read_feather.html). Example:
+{% raw %}`{{ read_feather() }}`{% endraw %} passed to [pandas.read_feather()](https://pandas.pydata.org/docs/reference/api/pandas.read_feather.html). Example:
=== "Input"
- \{\{ read_json('tables/data.feather') \}\}
+ {% raw %}
+ ```markdown
+ {{ read_json('assets/tables/data.feather') }}
+ ```
+ {% endraw %}
=== "Output"
- {{ read_feather('tables/data.feather') }}
+ {{ read_feather('assets/tables/data.feather') | add_indentation(spaces=4) }}
## read_excel
-`{{ read_excel() }}` passed to [pandas.read_excel()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html). Example:
+{% raw %}`{{ read_excel() }}`{% endraw %} passed to [pandas.read_excel()](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html). Example:
=== "Input"
- \{\{ read_excel('tables/excel_table.xlsx', engine='openpyxl') \}\}
+ {% raw %}
+ ```markdown
+ {{ read_excel('assets/tables/excel_table.xlsx', engine='openpyxl') }}
+ ```
+ {% endraw %}
=== "Output"
- {{ read_excel('tables/excel_table.xlsx', engine='openpyxl') }}
+ {{ read_excel('assets/tables/excel_table.xlsx', engine='openpyxl') | add_indentation(spaces=4) }}
!!! info "Reading xlsx files"
You might get a `XLRDError('Excel xlsx file; not supported',)` error when trying to read modern excel files. That's because `xlrd` does not support `.xlsx` files ([stackoverflow post](https://stackoverflow.com/questions/65254535/xlrd-biffh-xlrderror-excel-xlsx-file-not-supported)). Instead, install [openpyxl](https://openpyxl.readthedocs.io/en/stable/) and use:
- \{\{ read_excel('tables/excel_table.xlsx', engine='openpyxl') \}\}
+ {% raw %}
+ ```markdown
+ {{ read_excel('assets/tables/excel_table.xlsx', engine='openpyxl') }}
+ ```
+ {% endraw %}
## read_raw
-`{{ read_raw() }}` inserts contents from a file directly. This is great if you have a file with a table already in markdown format.
+{% raw %}`{{ read_raw() }}`{% endraw %} inserts contents from a file directly. This is great if you have a file with a table already in markdown format.
It could also replace a workflow where you use the [snippets extension to embed external files](https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#embedding-external-files).
Example:
=== "Input"
- \{\{ read_raw('tables/markdown_table.md') \}\}
+ {% raw %}
+ ```markdown
+ {{ read_raw('assets/tables/markdown_table.md') }}
+ ```
+ {% endraw %}
=== "Output"
- {{ read_raw('tables/markdown_table.md') }}
+ {{ read_raw('assets/tables/markdown_table.md') | add_indentation(spaces=4) }}
diff --git a/mkdocs.yml b/mkdocs.yml
index 4240b3c..1439a67 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -48,6 +48,7 @@ theme:
plugins:
- search
+ - macros
- table-reader:
data_path: "docs/assets"
- git-authors: