Configureable markdown formatting

[inktrap]

Context

I prefer my documents to look like this:

#·this·is·a·heading

·-·this·is·a·list
·-·another·item
·····-·this·is·a·sublist·entry·
·····-·inteded·by·4·spaces
·-·one·last·list·entry


##·let's·have·a·subheading·here

And·some·more·text


#·another·big·heading

Some·text.·And·some·more·text

So I'd like to have:

• list item indented by a space
• sublist item indented by 4 spaces
• headings/subheadings separated by two linefeeds

This is not exhaustive, it's just an example for how I would like my documents to look like.
Edit: We could check/warn if the chosen settings are not compliant with commonmark. I added · for spaces.

Proposal

A solution would be to provide settings/options to make the style more configureable.
Or to have the ability to add a custom style.

This could also be solved if a markdown renderer would be a selectable renderer in executeablebooks/markdown-it-py, after all that issue brought me here, and it is still open.

Related to that, many older issues for markdown-it-py are about renderers (how do I add my own, plaintext renderer, …). Markdown rendering seems like a complicated problem for everyone. Maybe this could be solved by adding a mapping to panflute, as it was mentioned in another issue?

Sorry, if this proposal is kind of vague, but it seems that the issue spans multiple projects.

Tasks and updates

• decide if this is more an issue that should be tackled within markdown-renderer-it or mdformat
• decide wether it is a manageable task to add docs/renderes to markdown-renderer-it
• check how options/settings could be specified for mdformat (personally I would love to have black for markdown files

[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! 🎉

[hukkin]

Thanks for the issue!

Here's my thoughts on adding configuration to mdformat. The docs also discuss this briefly.

personally I would love to have black for markdown files

If what you mean is literally Blackening Python codeblocks within a Markdown document, then that is a thing that already exists: https://github.com/hukkin/mdformat-black

Also see other plugins https://mdformat.readthedocs.io/en/stable/users/plugins.html

[hukkin]

While I'm not a huge fan of introducing numerous config knobs, I have recently considered having two modes:

• --simple: the default. Optimizes for small diffs and a simple style that is easy to write manually. No word wrap. Non-numbering for lists. Perhaps --- (3 chars long) as thematic break. Minimal simple tables with mdformat-tables. ATX headings only.
• --pretty: Optimizes for prettiness. Perhaps word wrap by default? Long thematic breaks. Numbering correction for lists. Pretty tables with mdformat-tables. Perhaps setext headings.

I haven't committed to actually accepting or implementing this but it's something I've though of.

[inktrap]

Thanks for your replies :) Indeed the motivation behind a configuration is that I would like "pretty" markdown files, pretty as in: markdown structured in a way that emphasizes the different structures so that they are recognizeable as markdown, with syntax highlighting only. Being simple and readable is one of the key-advantages of markdown. If I'll write:

Some text

# And then a heading

and some more text

That heading doesn't stand out enough. With a preceeding newline, it does.

The comparison to black should underline the importance that such a tool would have for me personally and the status it could have in general <3

But have you considered doing this in a config-oriented way? This, and some --incude --exclude flags seem to be a way to do this and I (personally) would lean towards being consistent with other formatters or linters.

"sensible defaults" could mean to be at least compliant with the commonmark-spec, but it could also mean to produce output that is compliant and "pretty". Have you thought about a --minimal setting? E.g. give me the most minimal, diffable output that is still compliant? That is another perspective on it. I guess the way we work with markdown seems different which is quite interesting.

I know about the plugins and they are not only the right way to implement this but also didacticly valueable. If someone asks me how they should write their plugin system, I would point them to mdformat.

[hukkin]

But have you considered doing this in a config-oriented way? This, and some --incude --exclude flags seem to be a way to do this

To clarify: Black also very much strives for no or low configurability. The flags you point to are for including and excluding files/filenamse, not syntax or style features.

Have you thought about a --minimal setting?

Yeah this sounds a lot like what I named --simple earlier (but perhaps your name is better).

If someone asks me how they should write their plugin system, I would point them to mdformat.

Very happy to hear this! And yeah, it's worth noting that even if I reject everything proposed here and we make zero changes to mdformat, it is possible to implement everything discussed here so far simply by creating plugins such as mdformat-pretty and mdformat-simple.

Would it be a good idea to separate the markdown formatter into a more general one that is useable with markdown-it-py? They have an issue about markdown-rendering too.

The mdformat.renderer.MDRenderer is arguably already a general markdown_it renderer and usable with markdown-it-py. The issue you refer to is open mostly for documentational reasons.

[inktrap]

To clarify: Black also very much strives for no or low configurability. The flags you point to are for including and excluding files/filenamse, not syntax or style features.

Ah sorry, you are right, seems I didn't read the manual well enough. I had stuff like pylint in mind where you can include/exclude linting rules.

Perhaps I'll share some thought about this:

Python is syntactically more restricted what it even allows to format, so I would say there are less points left to discuss how one should format the stuff that allows change.

In contrast, and definitly before commonmark, markdown was pretty "diverse" and ambiguous, so there are different "ways" people are still used to today. It is not necessary to accomodate all these different styles, and you already said that configurabilty (neither for mdformat nor the renderer) isn't a goal. It would be convenient for me, but that is not important.

But in order to have less difference that would have to be accommodated (by configurability), and in order for mdformat to have a similar role to black (because it works for many people in a useful way), the important question is how markdown is used. That's why I found it so interesting that you are leaning more towards a minimal, diffable style.

The main point I would like to make is that markdown is a format with the intend to be read and written by humans, and the markdown markup reflects the function of the different syntactical elements. It works as a lightweight markup language, and it works in a typographical sense without changing the format. And that should be reflected in the (or at least one) formatting style.

Otherwise it would be severly limiting that

mdformat is an opinionated tool that attempts to keep formatting style changing configuration to its minimum. New configuration will only be added for a very good reason and use case.

And about the way to do this:

it is possible to implement everything discussed here so far simply by creating plugins such as mdformat-pretty and mdformat-simple

Which I would be perfectly happy with :)

[KyleKing]

I finally finished mdformat-mkdocs that formats list indents to 4-spaces and might help resolve the list-indent issue on bitbucket and the initial request

While this plugin doesn't support extra new lines before the header, you can use my plugin as an example on modifying the POSTPROCESSORS