[Snippet] Add support to csv file, and auto convert to markdown table

[copdips]

Description

Hello,

Currently, I can write a markdown syntaxed table in a markdown file, and inject it into another markdown file by using snippet feature like this:

--8<-- "random_data.md"

The issue is that, if I have a big table of random_data, with long lines, the markdown table (the source code part) is less readable and editable.
I would like to save the table in csv format as my editor has some nice plugins to work with csv files on highlighting, filtering, editing, etc.

And I would like to see the Snippet extension can automatically convert the csv file to markdown table when rendering.

--8<-- "random_data.csv"

My current workaround is to keep the csv file, and during CICD process, I've a script to convert the csv to markdown.

Benefits

Making large markdown table more editable and readable during sourcering.

Solution Idea

No response

[facelessuser]

People have various niche things they would love to have implemented, but I unfortunately do not have the time to provide custom solutions for everyone's niche needs.

What you want can be accomplished within the existing framework. You can use a custom fence. I have a recent issue where I explored their niche case here: #2240.

Essentially, you could inject your CSV in a code block, and with custom fences, provide your own CSV language type and process the CSV content any way that you'd like. You would need to write the processing and provide the function to the SuperFence extension as described in the documentation: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/#custom-fences.

```csv-table
--8<-- "random_data.md"
```

Another option is to use the current block extension API to write you own custom block extension: https://facelessuser.github.io/pymdown-extensions/extensions/blocks/api/.

I simply cannot provide custom solutions for everyone, sorry.

[copdips]

Thx a lot for the details !
I close this issue, and will try to find a solution with your tips.

[copdips]

@facelessuser
I tested your example given in #2240, it nearly works for my csv file use case, but I'm blocked by the last step.

My tried this in my markdown file:

  ```csv
  my_csv_path.csv
  ``` 

By using your example, I created a function md_csv_render(), the input src gets value my_csv_path.csv, and then I can use any python module (for e.g. this one) to convert it to markdown content or save the markddown content into a file. So far so good.

But the probleme is that, say, in md_csv_render(), I computed two vars based on input src:

• text: the converted markdown table content
• md_file_path: the path to file where holds the generated markdown table content

I tried to return in 3 ways:

1. the converted markdown content, so text
2. f'\n```markdown\n{text}\n```\n'
3. return md, where md = markdown.markdown(text)
4. f'--8<-- "{md_file_path}"

None of them works, the 3 first are shown as raw text (the value of text var) when rendering in mkdocs material. And last one is shown as : --8<-- "my_markdown_table_file_path.md".

[copdips]

Yes, I tried now returning a html from csv inside md_csv_render() in fenced code, that works, I got a table rendered in Mkdoc Material, but the table style is not beautiful, and not consistent with other tables rendered by markdown table directly.

What I need is that, say I have a markdown page with content:

# Title

```csv
my_csv_file.csv
```

I need superfence to:

1. convert the my_csv_file.csv to my_md_table.md
2. replace:

   ```csv
   my_csv_file.csv
   ```

   by: --8<-- "my_md_table.md"
   or by the content of "my_md_table.md" directly

As by my test, if I generate my_md_table.md in advance, and use it as --8<-- "my_md_table.md", Mkdoc Material can render it as a table, and with the same style as other tables.

My current workaround is:

1. use --8<-- "my_md_table.md" even the file doesn't exist in the repo.
2. during CICD, I call a script to generate the file my_md_table.md from my_csv_file.csv on live.

I would like to see if superfence can do the convert part for me, and I just need to add a csv code block like following:

```csv
my_csv_file.csv
```

or like this: --8<-- "my_csv_file.csv"

And finally, the reason of this feature, editing csv file is much easier in editor than editing markdown table.

[facelessuser]

I don't know what you mean by "material isn't making it beautiful". Material applies styling to the HTML. If Material isn't applying the styling, there is a reason. What does Material require to make it beautiful? Once you can tell me that, you just need to do that to the HTML. I need root cause, not symptoms to help you.

[copdips]

I will show you a real example, hereunder my markdown file source code :

# Rendering CSV as Markdown table in Mkdocs Material

| name | age |
| ---- | --- |
| aa   | 11  |
| bb   | 22  |

--8<-- "test.md"

```csv
test.csv
```

• file test.md contains the content of the markdown table shown in the first part.

  

• file test.csv contains the same thing but in csv format

  

The above markdown file is rendered by Mkdocs Material as shown below:

the third table which is a html converted from the csv file is not as beautiful as the others.

And my fence code format code is :

import pandas as pd

... other functions

def md_csv_render(src="", language="", class_name=None, options=None, md="", **kwargs):
    """Formatter wrapper."""

        df = pd.read_csv(src)
        return df.to_html()

I registered it in mkdocs.yml as:

  - pymdownx.superfences:
      custom_fences:
        - name: csv
          class: csv
          format: !!python/name:tools.pymdownx_md_render.md_csv_render

[facelessuser]

You still aren't giving me the root cause. Table sorting in Material is being done by a JS library once loading into the browser. So the JS library expects something in order to "prettify" the table. So that leads me to believe the output of df.to_html is different than what the Markdown table is rendered as. So my question is, what is the difference?

Basically, you haven't properly debugged the why. The why is everything in understanding the issue. Alternatively, you can have panda output the Markdown and just run it through Python Markdown with the tables extension and then return the HTML that way.

---

1. Look at Material's docs on sorting: https://squidfunk.github.io/mkdocs-material/reference/data-tables/?h=tab#sortable-tables

Here is there example JS that finds the tables and adds sorting. Notice it looks for tables without a class.

document$.subscribe(function() {
  var tables = document.querySelectorAll("article table:not([class])")
  tables.forEach(function(table) {
    new Tablesort(table)
  })
})

Let's read Pandas documentation: https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.to_html.html. It seems to attach a class dataframe.

>>> df = pd.DataFrame(data={'col1': [1, 2], 'col2': [4, 3]})
>>> df.to_html()
'<table border="1" class="dataframe">\n  <thead>\n    <tr style="text-align: right;">\n      <th></th>\n      <th>col1</th>\n      <th>col2</th>\n    </tr>\n  </thead>\n  <tbody>\n    <tr>\n      <th>0</th>\n      <td>1</td>\n      <td>4</td>\n    </tr>\n    <tr>\n      <th>1</th>\n      <td>2</td>\n      <td>3</td>\n    </tr>\n  </tbody>\n</table>'

If Pandas is not outputting the info the way you want and you can't configure it to do it the way you want, just use Python Markdown.

>>> import pandas as pd
>>> import markdown
>>> df = pd.DataFrame(data={'col1': [1, 2], 'col2': [4, 3]})
>>> markdown.markdown(df.to_markdown(), extensions=['tabels'])
'<table>\n<thead>\n<tr>\n<th style="text-align: right;"></th>\n<th style="text-align: right;">col1</th>\n<th style="text-align: right;">col2</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td style="text-align: right;">0</td>\n<td style="text-align: right;">1</td>\n<td style="text-align: right;">4</td>\n</tr>\n<tr>\n<td style="text-align: right;">1</td>\n<td style="text-align: right;">2</td>\n<td style="text-align: right;">3</td>\n</tr>\n</tbody>\n</table>'

[copdips]

Thank you so much, my mistake was to convert it to pandas default html, in fact, it should be converted to markdown table's html as you showed in your response.

Now it works like a charm !
And just a little typo on tabels, and to set the alignment to left, the modified code is:

df = pd.read_csv(src)
df.columns = [f":{col}" for col in df.columns]
return markdown.markdown(df.to_markdown(index=False, tablefmt="github"), extensions=["tables"])