Support @import statement like Markdown Preview Enhanced

[Rj40x40]

I use Markdown Preview Enhanced when I use Visual Studio Code to edit Markdown files. Markdown Preview Enhanced can use the @import statement when importing tables, so I'm using it. But MkDocs doesn't support @import statements, so it would be great if the table-reader plugin could support them. I tried cloning it locally to support simple @import and it works fine.

[timvink]

Hi @Rj40x40,

So after some searching I support you mean this functionality: https://shd101wyy.github.io/markdown-preview-enhanced/#/file-imports

Mkdocs uses jinja2 templates, which have the {{ and }} syntax. If I add an additional syntax, this might break other use cases. For example, @import is also a CSS statement, so it's not unreasonable to expects some users to have those strings in their markdown files.

I see why you find this useful though. We could put this behind an option flag though, like:

  - table-reader:
      enable_import_statement: false # default

A follow-up problem might be that you want to specify some of the keyword arguments.

If we require the @import statements to be on their own, unique line, we could also allow follow-up keywords arguments, like so:

@import 'tables/basic_table.csv' colalign=("left",)

And, we'll have to use the extension of the file to find the correct reader (csv, json, tsv, xlsx, etc.).

I'm open for PRs :)

[Rj40x40]

I didn't know the details of MkDocs nor the jinja2 templates. It's not good to add another syntax when there is a certain one. Thank you for your explanation.

I agree using option flags to control syntax control.

My prototype code doesn't support optional flags, nor follow-up keywords, but I'll do a PR.

In my prototype code, the relative file paths in @import statements are from the Markdown file location. Also, like Markdown Preview Enhanced, it only supports double quotes, not single quotes.

The prototype code supports image files as well as csv files. There seems to be a follow-up keyword defined for image files, but this is not supported. Since the image file is not a table, I thought that it was out of the scope of this mkdocs-table-reader-plugin, but I just put it in as a trial.

[timvink]

What you can also do, is create a new plugin, mkdocs-preview-enhanced, so you can fully mimic the same behavior. That's even clearer for users because it's a new syntax and might be easier for you to code up (also because the path works differently, relative to markdown file).

You can fork this repo and reuse all the code you want !

[timvink]

This is the place to start: https://www.mkdocs.org/dev-guide/plugins/

[Rj40x40]

Thank you for your reply. As you say, there are some difference so I agree making another plugin for easy choosing. It's my first challenge, but I'll try to make a plugin.

The CSV converting part is one of difficult parts for me. I will copy your code with great thanks

[timvink]

Cool, good luck and let me know once you've finished. Maybe I can link to your plugin from this one.

[timvink]

I see you started on the plugin -- nice!

I just released a new version of this plugin which implements relative paths (one of the reasons the @import syntax wasnt a good match).

Still think a separate plugin is the right way to go though. Once you're done, make sure to promote your plugin by adding it to the overview here: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins

Also, let me know once it's ready. I might add a section with 'alternatives' to this plugin to inform users of different options that might fit their use case better

[Rj40x40]

Thank you for your comment.

My plugin worked fine in my own testing, so I published it. I will try to register for MkDocs-Plugins soon.