Documentation for using plugins with MDRenderer

[sixhobbits]

Context

The plugins documentation shows how to pass plugins to mdformat.text, but not how to do this using the Renderer API.

At the moment I have rendered = MDRenderer().render(tokens, md.options, env) which works fine for plain markdown, but not if I have front_matter tokens which then gives the error below.

It would be good if the documentation made it clearer if this can be done using mdformat.renderer directly.

Traceback (most recent call last):
  File "/Users/g/gbin/mdh", line 25, in <module>
    run(fle, findtext, replacetext)
  File "/Users/g/gbin/markdown_helper/fix_image_paths.py", line 31, in run
    fix_image_paths(text, findtext, replacetext)
  File "/Users/g/gbin/markdown_helper/fix_image_paths.py", line 23, in fix_image_paths
    rendered = MDRenderer().render(tokens, md.options, env)
  File "/opt/homebrew/lib/python3.10/site-packages/mdformat/renderer/__init__.py", line 57, in render
    return self.render_tree(tree, options, env, finalize=finalize)
  File "/opt/homebrew/lib/python3.10/site-packages/mdformat/renderer/__init__.py", line 91, in render_tree
    text = tree.render(render_context)
  File "/opt/homebrew/lib/python3.10/site-packages/mdformat/renderer/_tree.py", line 11, in render
    text = renderer(self, context)
  File "/opt/homebrew/lib/python3.10/site-packages/mdformat/renderer/_context.py", line 50, in render_children
    return separator.join(out for out in render_outputs if out)
  File "/opt/homebrew/lib/python3.10/site-packages/mdformat/renderer/_context.py", line 50, in <genexpr>
    return separator.join(out for out in render_outputs if out)
  File "/opt/homebrew/lib/python3.10/site-packages/mdformat/renderer/_context.py", line 49, in <genexpr>
    render_outputs = (child.render(context) for child in node.children)
  File "/opt/homebrew/lib/python3.10/site-packages/mdformat/renderer/_tree.py", line 10, in render
    renderer = context.renderers[self.type]
KeyError: 'front_matter'

Proposal

• Extend the docs with an example how to use plugins with Renderer if this is possible
• I am happy to write the docs and more examples covering frontmatter, tables, etc if someone can show me a basic example of how use Renderer() with a plugin.

Tasks and updates

No response

[welcome]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! 🤗

If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.

If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).

Welcome to the EBP community! 🎉

[finlaysawyer]

For anyone else that comes across this thread, here's how I got mdformat-tables working with the Rendering API:

from mdformat.renderer import MDRenderer
import mdformat_tables

rendered = MDRenderer().render(
    parsed, {"parser_extension": [mdformat_tables]}, {}
)

I'll see if I can PR an update to the docs to include this later.