You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -38,7 +38,7 @@ In your markdown files you can now use:
38
38
{{ read_csv('path_to_table.csv') }}
39
39
```
40
40
41
-
Where the path is relative to the location of your project's `mkdocs.yml` file (although you can [change that](https://timvink.github.io/mkdocs-table-reader-plugin/options) to be relative to your `docs/` directory).
41
+
Where the path is relative to the location of your project's `mkdocs.yml` file, _or_ your project's `docs/` directory, _or_ the location of your markdown source file (all 3 possible locations will be searched, in that order).
42
42
43
43
- There are [readers](https://timvink.github.io/mkdocs-table-reader-plugin/readers/) for `.csv`, `.fwf`, `.json`, `.xlsx`, `.yaml` and `.tsv` files. There is also the `read_raw()` reader that will allow you to insert tables (or other content) already in markdown format.
Copy file name to clipboardExpand all lines: docs/howto/project_structure.md
+10-38Lines changed: 10 additions & 38 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -26,11 +26,15 @@ If you only want to include an occasional table in a specific markdown file, jus
26
26
\{\{ read_csv("another_table.csv") \}\}
27
27
```
28
28
29
-
This works because the [option](../options.md)`search_page_directory` defaults to `True`.
29
+
In `page.md`, to read `another_table.csv`, you can choose to use:
30
+
31
+
- <code>\{\{ read_csv("docs/folder/another_table.csv") \}\}</code> (Path relative to mkdocs.yml)
32
+
- <code>\{\{ read_csv("folder/another_table.csv") \}\}</code> (Path relative to docs/ directory)
33
+
- <code>\{\{ read_csv("another_table.csv") \}\}</code> (Path relative to page source file)
30
34
31
35
## Re-using tables across markdown files
32
36
33
-
If you want to reuse tables in multiple markdown files, you'll want to store them in a central directory, like `docs/assets/tables`.
37
+
If you want to reuse tables in multiple markdown files, or have many tables, you'll want to store them in a central directory, like `docs/assets/tables`.
34
38
That way, if you restructure your navigation, the links to the tables won't break either.
35
39
It's also great if you generate tables because the output directory will be the same.
36
40
@@ -45,44 +49,12 @@ Given the following project structure:
45
49
│ └── assets/
46
50
│ └── tables/
47
51
│ └── another_table.csv
48
-
│ └── page.md
49
52
└── mkdocs.yml
50
53
```
51
54
52
-
In `page.md`, to read `basic_table.csv`, you can choose to use:
53
-
54
-
- <code>\{\{ read_csv("docs/assets/tables/another_table.csv") \}\}</code> when `base_path`[option](../options.md) is set to `config_dir` (default)
55
-
- <code>\{\{ read_csv("assets/tables/another_table.csv") \}\}</code> when `base_path`[option](../options.md) is set to `docs_dir`
56
-
- <code>\{\{ read_csv("../another_table.csv") \}\}</code> if you want to use a relative path and `search_page_directory`[option](../options.md) is enabled (default). Note that `..` stands for "one directory up".
57
-
58
-
## A central table directory combined with same-directory tables
59
-
60
-
If you have some central tables that you want to reuse, and some tables that are specific to a page, you could use the following project structure:
61
-
62
-
```nohighlight
63
-
.
64
-
├── docs/
65
-
│ ├── tables/
66
-
│ | └── basic_table.csv
67
-
│ └── folder/
68
-
│ └── another_table.csv
69
-
│ └── page.md
70
-
└── mkdocs.yml
71
-
```
72
-
73
-
In `page.md`, to read `basic_table.csv`, you can choose to use:
74
-
75
-
- <code>\{\{ read_csv("docs/tables/basic_table.csv") \}\}</code> when `base_path`[option](../options.md) is set to `config_dir` (default)
76
-
- <code>\{\{ read_csv("tables/basic_table.csv") \}\}</code> when `base_path`[option](../options.md) is set to `docs_dir`
`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).
4
+
5
+
To enable `macros`, specify the plugin _before_`table-reader` in your `mkdocs.yml` file:
6
+
7
+
```yaml
8
+
plugins:
9
+
- macros
10
+
- table-reader
11
+
```
12
+
13
+
Now you can do cool things like dynamically load a list of tables:
14
+
15
+
16
+
```markdown
17
+
# index.md
18
+
19
+
{% set table_names = ["basic_table.csv","basic_table2.csv"] %}
Copy file name to clipboardExpand all lines: docs/options.md
+4-32Lines changed: 4 additions & 32 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,63 +10,35 @@ You can customize the plugin by setting options in `mkdocs.yml`. For example:
10
10
```yml
11
11
plugins:
12
12
- table-reader:
13
-
base_path: "config_dir"
14
13
data_path: "."
15
-
search_page_directory: True
16
14
allow_missing_files: False
17
15
select_readers:
18
16
- read_csv
19
17
- read_json
20
18
enabled: True
21
19
```
22
20
23
-
## `base_path`
24
-
25
-
The base path where `mkdocs-table-reader-plugin` will search for input files. The path to your table files should be relative to the `base_path`. Allowed values:
26
-
27
-
- `config_dir` (default): the directory where your project's `mkdocs.yml` file is located.
28
-
- `docs_dir`: the directory where your projects' `docs/` folder is located.
29
-
30
-
If you store your table in `docs/assets/table.csv`, you can insert it in any markdown page using <code>\{\{ read_csv("docs/assets/table.csv") \}\}</code>, or when `base_path` is `docs_dir`, with <code>\{\{ read_csv("assets/table.csv") \}\}</code>.
31
-
32
-
!!! info
33
-
34
-
Note that by default the plugin will _also_ search the page's directory but only when a table is not found.
35
-
36
-
For more examples see the how to guide on [project structure](howto/project_structure.md).
37
-
38
21
## `data_path`
39
22
40
-
The path to your table files should be relative to the `base_path`. If you use a folder for all your table files you can shorten the path specification by setting the `data_path`.
23
+
Default is `.`. Set a default path to the searched directories in order to shorten table filename specifications.
41
24
42
-
For example, if your table is located in `docs/tables/basic_table.csv`, you can set `data_path` to `docs/tables/` and leave `base_path` to the default `config_dir`. Then you will be able to use <code>\{\{ read_csv("basic_table.csv") \}\}</code> instead of <code>\{\{ read_csv("docs/tables/basic_table.csv") \}\}</code> inside any markdown page.
25
+
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`.
43
26
44
-
Default is `.`, which means you need to specify the path to your table files relative to the `base_path`.
27
+
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 <code>\{\{ read_csv("basic_table.csv") \}\}</code> instead of <code>\{\{ read_csv("docs/assets/tables/basic_table.csv") \}\}</code> inside any markdown page.
45
28
46
29
!!! info
47
30
48
31
Note that by default the plugin will _also_ search the page's directory but only when a table is not found.
49
32
50
33
For more examples see the how to guide on [project structure](howto/project_structure.md).
51
34
52
-
## `search_page_directory`
53
-
54
-
Default: `True`. When enabled, if a filepath is not found, the plugin will also attempt to find the file relative to the current page's directory.
55
-
56
-
!!! info
57
-
58
-
Note that even when `True`, the path relative to `data_path` is searched first,
59
-
and if a file is not found there, then the page's directory is searched.
60
-
61
-
For more examples see the how to guide on [project structure](howto/project_structure.md).
62
-
63
35
## `allow_missing_files`
64
36
65
37
Default: `False`. When enabled, if a filepath is not found, the plugin will raise a warning instead of an error.
66
38
67
39
## `select_readers`
68
40
69
-
Default: Selects all available readers. Specify a list of reader to improve documentation build times for large sites.
41
+
Default: Selects all available readers. Specify a list of readers to improve documentation build times for very large sites.
"title": "The base path where mkdocs-table-reader-plugin will search for input files. The path to your table files should be relative to the base_path.",
"title": "The path to your table files should be relative to the base_path. If you use a folder for all your table files you can shorten the path specification by setting the data_path.",
logger.warning(f"[table-reader]: The 'search_page_directory' configuration option is deprecated, it will always be searched. Please remove it from your mkdocs.yml.")
36
+
if"base_path"inself.config:
37
+
logger.warning(f"[table-reader]: The 'base_path' configuration option is deprecated. Both the config_dir and docs_dir will be searched. Please remove it from your mkdocs.yml.")
0 commit comments