Preprocessing of MD files

[Vasperous]

Hello! I am looking to try and expand the usage of tables. The current issue I face appears to be related to how rigid tables are in markdown.

The content I want to put in a table can be diverse and large in some cases, which is why collapsible blocks etc. are needed. To achieve this I have to generate the content I want to embed in the table in another markdown file and then copy the html output into the table. So something like this:

Generate MD individual cell content -> Generate HTML -> Copy and paste HTML into markdown table cell

I was going I could find something to help me do this. For example, Snippets plugin could do this but the Snippets data isn’t converted to html first. Also, the snippets plugin requires its own line. I use snippets all over the place and it is great, I just have this use case which doesn’t seem to fit.

Another example is using Macros plugin. Macros doesn’t require its own line but it won’t perform the processing of the markdown as far as I can tell which means I still need to generate the HTML from markdown separate.

Any thoughts or ideas on how to achieve this use case? Thank you!

[alexvoss]

I am not entirely sure what it is that makes the tables you talk about special, so what the requirements are you have. I assume just using Python Markdown to do the rendering does not do the trick for you?

When it comes to writing your customization, this sounds like a case for MkDocs hooks, specifically responding to the on_page_markdown event? You can also post-process the HTML with on_page_content.

[Vasperous]

@alexvoss thank you for the response. I was hoping there might be an existing plugin that I can use (if any one is aware of it). Basically I need a plugin (or modify one) to do the following:

1. Read a set of markdown files (not all the markdown files in a project, so these specific files need to be read and converted to HTML first)
2. Convert them to HTML
3. Perform a function similar to snippets or Macros (i.e., find and replace a variable name in the MD file with the HTML content produced in step 2)
4. Finish building the rest of the documentation

As for the use case, the best example I can give is wanting to put something like Admonition inside a table. To do this I need to create the admonition (collapsed by default but expandable), generate the HTML, using Chrome inspector copy the raw HTML. Paste the raw HTML back into my table in the MD file.

[alexvoss]

I may be wrong but this sounds like quite a specific case. I had a look in the MkDocs Plugin Catalogue but nothing sprang out to me that would help here. Perhaps someone else can recommend a possible solution.

Would you be happy to author the table in HTML (perhaps you already do?) and use the md_in_html extension to render the cell contents including admonitions?

For the admonitions, I would recommend using the new block syntax that the Pymdown Extensions provide, so you don't need to worry about indentation. You would need to activate them in mkdocs.yml instead of the standard admonitions.

Hope some of this helps.

[facelessuser]

Would you be happy to author the table in HTML (perhaps you already do?) and use the md_in_html extension to render the cell contents including admonitions?

Tables are cumbersome even in more advanced table extensions that can allow for more complex structures. Authoring in HTML with md_in_html is a pretty reasonable solution.