diff --git a/docs/reference/data-tables.md b/docs/reference/data-tables.md index 03b91d6a9..1099db430 100644 --- a/docs/reference/data-tables.md +++ b/docs/reference/data-tables.md @@ -182,3 +182,150 @@ numbers, filesizes, dates and month names. See the [tablesort documentation] [tablesort]: http://tristen.ca/tablesort/demo/ [instant loading]: ../setup/setting-up-navigation.md#instant-loading + +### Import table from file + +[:octicons-cpu-24: Plugin][table-reader-docs] + +You can also import data from a CSV or Excel file using the plugin [`mkdocs-table-reader-plugin`][table-reader-docs]. + +First, you will need to install it with `pip`: + +```sh +pip install mkdocs-table-reader-plugin +``` + +Then extend the `mkdocs.yml` file like this: + +```yaml +plugins: + - table-reader +``` + +Then, it is a simple process to import the data in to the Markdown files. + +=== "Import data from :fontawesome-solid-file-csv: CSV file" + + Let's use a :fontawesome-solid-file-csv: CSV in the local directory. The file may look like this: + + ```csv title="./data.csv" + col1,col2,col3 + r1c1,r1c2,r1c3 + r2c1,r2c2,r2c3 + r3c1,r3c2,r3c3 + ``` + + You can then add it to your :fontawesome-solid-file-arrow-down: Markdown page like this: + + ```md title="./markdown.md" + ... + + {{ read_csv('./data.csv') }} + + ... + ``` + +
+ + ... + + col1|col2|col3 + ----|----|---- + r1c1|r1c2|r1c3 + r2c1|r2c2|r2c3 + r3c1|r3c2|r3c3 + + ... + +
+ +=== "Import data from :fontawesome-solid-file-excel: Excel file" + + Let's use an :fontawesome-solid-file-excel: Excel file in the local directory. The file may look like this: + + ![][excel-file]{width="300px"} + + [excel-file]: https://i.stack.imgur.com/f32ks.png + + And you can add it to your :fontawesome-solid-file-arrow-down: Markdown page like this: + + ```md title="./markdown.md" + ... + + {{ read_excel('./Book1.xlsx', engine='openpyxl') }} + + ... + ``` + +
+ + It will then return a result like this: + + col1|col2|col3 + ----|----|---- + r1c1|r1c2|r1c3 + r2c1|r2c2|r2c3 + r3c1|r3c2|r3c3 + +
+ + !!! warning "Warning" + + You may receive an error if you use `engine='openpyxl'`. + + If this happens, you can resolve it by installing it using `pip`: + + ```sh + pip install poenpyxl + ``` + + Read more here: [pandas.read_excel][pandas-read_excel-engine] + + [pandas-read_excel-engine]: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html#:~:text=enginestr%2C%20default%20None + + !!! tip "Pro Tip: Multiple Sheets" + + If your Excel file contains multiple sheets, you may want to extend the function by adding the `sheet_name` parameter. + + It would look like this: + + ```md title="./markdown.md" + ... + + {{ read_excel('./Book1.xlsx', engine='openpyxl', sheet_name="Sheet1") }} + + ... + ``` + + By default, Pandas will grab the first sheet in the workbook. + + Read more here: [pandas.read_excel][pandas-read_excel-sheet_name] + + [pandas-read_excel-sheet_name]: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html#:~:text=sheet_namestr%2C%20int%2C%20list%2C%20or%20None%2C%20default%200 + +=== "Import data from other file types" + + The plugin [`mkdocs-table-reader-plugin`][table-reader-docs] also provides readers for other formats: + +
+ + - [`read_csv`][table-reader-read_csv] + - [`read_fwf`][table-reader-read_fwf] + - [`read_yaml`][table-reader-read_yaml] + - [`read_table`][table-reader-read_table] + - [`read_json`][table-reader-read_json] + - [`read_excel`][table-reader-read_excel] + - [`read_raw`][table-reader-read_raw] + +
+ + You can read more on their Docs website: [mkdocs-table-reader-plugin][table-reader-docs] + +[table-reader-docs]: https://timvink.github.io/mkdocs-table-reader-plugin/ +[table-reader-read_csv]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_csv +[table-reader-read_fwf]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_fwf +[table-reader-read_yaml]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_yaml +[table-reader-read_table]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_table +[table-reader-read_json]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_json +[table-reader-read_excel]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_excel +[table-reader-read_raw]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_raw