timvink / mkdocs-table-reader-plugin

MkDocs plugin that enables a markdown tag like {{ read_csv('table.csv') }} to directly insert various table formats into a page
https://timvink.github.io/mkdocs-table-reader-plugin/
MIT License
111 stars 18 forks source link

Add superfence notation #45

Open timvink opened 1 year ago

timvink commented 1 year ago

(inspired by this discussion)

Instead of {{ read_csv('table.csv') }} we could take inspiration from https://github.com/coddingtonbear/obsidian-csv-table and create a custom superfences notation like so:

```table-reader
filepath: table.csv


We could add the following extra options:

- `reader` (str) one of the pandas functions, like `read_csv`
- `keyword_arguments`, a dictionary, with named arguments, for example `encoding: 'utf-8'`
- `filter` (list of strings), where each is successively passed to `.query()`
- `sortBy` (list of strings), passed to pandas's `.sort_values()` 
- `maxRows` (int), passed to pandas's `.head()`
- `columnVariables` (list of strings), passed to `pandas's `.rename()`

You can already do all this by just using a [mkdocs hook to preprocess tables](https://timvink.github.io/mkdocs-table-reader-plugin/howto/preprocess_tables/). 

So if you read this & have a use-case for this, let me know!
roaldarbol commented 1 year ago

Hey Tim! Original poster of the discussion here. I might be biased, but I really like the Obsidian notation - the fact that it reads easily, feels void of actual code (which I really prefer in Markdown documents) is a big bonus I think. And the actions/options you listed above should be fine - I would try to match what has been done in the Obsidian plug-in as there is no need to re-invent the wheel, and their users have had a long time to post issues. Thanks for following up on the discussion and with your work on the plugin - I'm looking forward to testing it out!

In terms of a use-case, as I mentioned in the original post, I'm personally working on an open hardware project where we have a collection of parts in a file and want to showcase subsets of parts needed to make each build. :-)

timvink commented 1 year ago

I really like the Obsidian notation

I thought it would be easier to understand if I would follow the pandas arguments where possible. But it's not that much clearer anyway. Being able to copy markdown from obsidian and have it work in Mkdocs with only minimal changes is more vaiuable.

I'm looking forward to working on this one, but it's low-prio so probably going to take 1-2 months before I have some free time for hobby coding again :D

roaldarbol commented 1 year ago

No worries, this would be awesome, but not time critical. ;-) Looking forward to your implementation!