Indentation with 3 spaces breaks mkdocs

[ThmX]

Describe the bug

context
When I format my lists markdown using mdformat.

expectation
I expected the file to be correctly formatted with mkdocs.

bug
But instead the lists are merged due to the indentation with 3 spaces.

problem
This is a problem for people using mkdocs because files are not formatted as expected.
The documentation from mkdocs states that it needs 4 spaces as indentation:
https://www.mkdocs.org/user-guide/writing-your-docs/#:~:text=If%20a%20line%20is%20indented%20by%204

Reproduce the bug

A list of lists with 4 spaces as indent is correctly displayed in mkdocs

- Some list
    - A
    - B
    - C
- Something else

Which is then reformatted with 3 spaces and then both list are merged into one by mkdocs

- Some list
   - A
   - B
   - C
- Something else

List your environment

❯ python --version
Python 3.9.10

❯ python -m mdformat --version
mdformat 0.7.14 (mdformat_myst: 0.1.5, mdformat_tables: 0.4.1, mdformat_frontmatter: 0.4.1, mdformat_web: 0.1.0, mdformat_black: 0.1.1, mdformat_beautysh: 0.1.1,
mdformat_config: 0.1.3)

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

Firstly, I'd like to clarify that mdformat uses 2 spaces, not 3 spaces as unordered list item indentation.

Secondly, I assume you refer to this piece of text in mkdocs docs:

If a line is indented by 4 or more spaces, that line is assumed to be an additional line of the value for the previous keyword. A keyword may have as many lines as desired. All lines are joined into a single string.

That text has nothing to do with list item indentation. It is under a section that describes "MultiMarkdown Style Meta-Data", which is syntax that CommonMark is unaware of, so mdformat will not respect it unless you create a plugin supporting it.

[ThmX]

Oh you are right, I read too fast :-/

However, the issue is still there. I cannot find the minimum indentation width in the documentation from mkdocs, but from what I see in my documentation, it needs 4 spaces to be able to format correctly. Otherwise it simply flatten all the lists.

Plus I must admit I like the indentation with 4 spaces (same as in PyCharm basically)

I created PR #318 as a fix by adding an option to set the minimum indentation width.

What do you think?

Not sure if I could create it as a plugin instead (also if it makes sense having this as a plugin)

[hukkin]

However, the issue is still there. I cannot find the minimum indentation width in the documentation from mkdocs, but from what I see in my documentation, it needs 4 spaces to be able to format correctly. Otherwise it simply flatten all the lists.

Do you have a repository or a way to reproduce this? I find this hard to believe, seeing that mkdocs uses https://pypi.org/project/Markdown/ as its Markdown parser and that is an implementation of John Gruber's Markdown. John Gruber's Markdown works fine with 2 spaces as indent width.

What do you think?

Currently, I don't think there's good enough justification for adding configuration knob for this. If you want, you can achieve what you want with a plugin.

[hukkin]

I did a little digging.

You are right that mkdocs requires a 4 space (or a tab) indentation. The Markdown library that mkdocs uses seems to interpret John Gruber's Markdown spec in the way that this is the correct thing to do. It is noteworthy that John Gruber's own reference implementation interprets the spec differently, allowing 2 or 3 space indentations (you can try it out here).

*sigh* This is why I wish all projects conformed to an unambiguous spec (i.e. CommonMark). It seems mkdocs is unwilling to do so.

While mdformat is a "CommonMark compliant Markdown formatter", meaning it really has no obligation to support this use case or mkdocs's parser, mkdocs is popular enough that I think we should come up with a solution: either a plugin or configuration. An mdformat-mkdocs plugin would be nice as that could also include support for the non-standard admonition syntax (and possible other peculiarities that mkdocs requires).

[danhje]

I'm having the same issue, I'd love using mdformat at a pre-commit hook, but can't with mkdocs. Glad you're looking for a solution.

[KyleKing]

I could start on a mdformat-mkdocs plugin? I'm starting to get familiar with the ecosystem

[KyleKing]

As a quick update, I am making progress on mdformat-mkdocs. I am running into an issue where the rendered HTML doesn't match and pre-commit fails, but once I resolve that, the package should be ready!

[KyleKing]

Done! If you run into any issues, open a ticket here: https://github.com/KyleKing/mdformat-mkdocs