Markdown Renderer

[chrisjsewell]

i.e. round trip conversion md-tokens-md. This would be useful for example to act as a formatter, whereby the max-line length could be specified and other options like:

• whether to use STX header for top level
• when to use * or _ to denote bold/emphasis (particularly if nested)

[teucer]

That might come handy for some other use cases: the code blocks could be executed and their output put back into markdown file.

[hukkin]

Hi! I wrote a renderer like this a few months ago for a Markdown formatter, but only now stumbled upon this issue.

All of the renderer code can be found in this package (the renderer class itself is declared in __init__.py).

Maybe that could be interesting/inspiring/useful for anyone implementing a renderer of their own. I also don't have any problem with upstreaming the renderer class as is, if someone sees it as a good fit for this project.

[chrisjsewell]

Oh awesome great work, the pre-commit was exactly what I had in mind!

I also don't have any problem with upstreaming the renderer class as is, if someone sees it as a good fit for this project.

I'd certainly be interested in moving the package into the executablebooks organisation, with you as a maintainer? But obviously that's entirely up to 😄

also cc @a-vrma

[chrisjsewell]

Its funny because I've literally just written a pre-commit hook today: https://github.com/executablebooks/scss-compile

[hukkin]

I'd certainly be interested in moving the package into the executablebooks organisation, with you as a maintainer?

Ok so first lets clarify one thing. By "the package" do you mean mdformat._renderer package that contains the renderer class? Or mdformat distribution package as whole? I hate that Python terminology is ambiguous here... :)

The way I see it, in the scope of this issue it would make sense to discuss moving the renderer class to mardown-it-py.

If what you meant was transferring the repository altogether, then I'm open to consider that too, but we might want to discuss it in another issue in mdformat's issue tracker?

[chrisjsewell]

Yep mdformat as a whole 👍 mdformat._renderer integrates in nicely with that package, so I don't see it being that beneficial to split them apart.

Also I would rather mardown-it-py was purely the port of markdown-it (I'm already looking to split off the plugins into a separate package #30)

but we might want to discuss it in another issue in mdformat's issue tracker?

sure wherever 😄

It looks like a very well maintained package to me, with all the mod-cons lol (pre-commits, GH workflows, etc), so I certainly would be looking to "interfere" much; just propose a few additions and look to promote/utilise it in the rest of the EBP stack (myst-parser, jupyter-book, etc)

[hukkin]

but we might want to discuss it in another issue in mdformat's issue tracker?

sure wherever 😄

Haha ok lets do this here then. I slightly misunderstood the intent of this issue (thinking it wants to add the renderer to this repo) so thought this would be very off topic.

I'm thinking transferring the repo might be a good idea:

• More visibility, more eye pairs, more potential contributors. This is what FOSS is all about.
• Code is coupled with markdown-it-py anyways
• If I become unresponsive or busy as a maintainer, this is probably the best possible organization to take over the ownership.

Some rules I would like to start off with though:

• I keep sole ownership of the PyPI package. Willing to make EBP people maintainers though.
• Master branch is protected from everyone (including me)
• Passing CI always required before merge
• I start off as the only maintainer (my approval needed for every merge)

Does this seem reasonable to you? Anything to add from your side? If not, I'm willing to do the transfer, just have to look into the technicalities. Never done that in github before.

[chrisjsewell]

so thought this would be very off topic

No nothing's off-topic lol, the intent was mainly just a TODO item for myself not to forget!

I'm thinking transferring the repo might be a good idea...

Yep that's the idea 👍 it hopefully just allows for a little more guarantee of long-term package maintenance and groups packages of similar interest in a single place (~python packages focussed on documentation)

Does this seem reasonable to you?

Yeh all sounds good to me. All the EBP packages are set up with protected master and CI 👍
I/we wrote some general EBP guidelines here https://executablebooks.org/en/latest/contributing.html, but as long as the package is well maintained (which it is) I'm not going to start telling you to change anything (feel free to suggest improvements to those guidelines though 😄)

just have to look into the technicalities. Never done that in github before.

So I've sent you a request to join the EBP org, at which point you can transfer ownership

At this point I need to go in and set you to full admin privileges and then you can go in and ensure all the branch protections are to your requirements. To note though, I don't think there is a way to physically block organisation owners (me and a few others) from having access to admin controls.
So there is a modicum of trust required there 😬, but I'm sure I speak for all of us, that it would just not be in our best interest to act in bad faith against collaborators
(also I just don't have the time or inclination lol)

[hukkin]

Alrighty, here's the new address: https://github.com/executablebooks/mdformat 🥳

[chrisjsewell]

thanks 🙏

Before closing this issue I should

• add a renderer plugin section in the documentation soon; linking to myst-parser and mdformat
• think about adding Markdown renderer methods to the existing plugins

[inktrap]

So after two years this issue is still open while #164 is not. Other older issues that are still open are also about renderers and the docs only mention the html-renderer. So what is the plan here? It seems like rendering markdown could be a unique ability of this project as it is mentioned there.

I had a look at mdformat and it is not clear how I could ulitize parts of mdformat to create a markdown renderer. I created an issue there that also mentions the panflute idea.

I just want (somewhat configureable) markdown rendering, given a Token stream or Tree, and given that there are multiple ways to achieve this, I wanted to re-vitalize this discussion here. Intuitively the best idea would be to separate the markdown renderer of mdformat into its own project and make it useable by mdformat and markdown-it-py.

[inktrap]

Or asked another way: What does this project need? More docs? A standalone markdown renderer? A decision about the panflute idea? More people willing to pitch in? I don't want to approach this only from the perspective of my needs.

[hukkin]

I had a look at mdformat and it is not clear how I could ulitize parts of mdformat to create a markdown renderer.

This MDRenderer class here is a Markdown renderer compatible with markdown_it.MarkdownIt. It is already public API so can use it as a library.

I just want (somewhat configureable) markdown rendering

The configurability part is something I've not very excited to maintain myself. But the license is MIT so as long as you keep the license and copyright, you can make it as configurable as you want and redistribute yourself.