Expected behaviour when indenting twice (two tabs) in admonitions?

[StarfallProjects]

A visual bug recently appeared: admonition content being displayed as code (example: https://docs.n8n.io/user-management/ldap/). I can't pinpoint exactly when it started, but only the last few days.

However, I am not sure if this is a bug with the theme, or intended behaviour, so before I file a bug report: is it intended that when you put two tabs in an admonition it renders as code?

For example, this inserts code formatting:

!!! note "an example note"
<tab><tab>Contents

While this does not:

!!! note "an example note"
<tab>Contents

I would have expected the tabs to be replaced with spaces (we actually had to do a workaround to prevent this in our code blocks), so am a bit surprised they're affecting it at all. The equivalent spaces (4) don't result in code formatting. I have done a minimal reproduction, and it isn't our workaround causing this - it occurs without it in place.

@squidfunk this is an n8n problem, not a personal site problem, in case that affects response time :-)

[StarfallProjects]

Ok the more I look at this the more I think not-bug. Python Markdown will be replacing two tabs with eight spaces?
You can probably ignore this - although the fact it only started being an issue recently still gives me pause.

[alexvoss]

Thanks for reaching out. I think this is a side effect of you being able to put code into an admonition. Indentation really does matter in Markdown.

(Speaking as someone who is not a fan of languages where indentation matters - did we run out of delimiters or were they just too difficult to reach on non-US/UK keyboards?)

[squidfunk]

Hmm, I'm pretty sure this has nothing to do with Material for MkDocs, but with Python Markdown extensions in general. Could you please try the mkdocs and readthedocs theme if they exhibit the same behavior? If yes, please report this to Python Markdown.

[facelessuser]

So, I will give some insight into the recent surfacing of this and state it is not a bug. Admonitions, in this format, have always required that the content be indented. Additionally, indented blocks are generally treated as code blocks in Markdown. So to have indented code blocks under an admonition you would have to indent twice.

Now, there was a bug that I recently fixed in admonitions. Indented code blocks were not treated properly. Python-Markdown/markdown#1329

Now that this has been fixed, indented code blocks now work properly when they are the first block under admonitions, which is likely what you are seeing.

With all of that said, I've never been a fan of having to indent the all content under Admonitions, Details, Definitions, Tabs, etc. Pymdown Extensions implemented plugins for details and tabs using this Admonition style approach because it was a bit complicated to create such blocks with complex levels of blocks under them under Python Markdown. Recently though, I have created a way to do so without requiring all of this indentation.

If you do not like these "indentation" style containers, you can use Pymdownx block plugins for Admonition, Details, Tabs, etc. https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/admonition/.

[alexvoss]

I am working on an example, will share. Custom admonition will need an extra.css but the basics are there as the div for a custom admonition has the appropriate custom class.

[facelessuser]

The "block" style replacements for various plugins are 100% compatible with the old "indented" style. They should be compatible with existing styles.

[facelessuser]

What I mean is the output is the same even if the input syntax is different.

[alexvoss]

Yep, and it works nicely. Will make a PR for the Material for MkDocs examples but need to figure out how to flag this is based on a feature that is still experimental. Hope to get this done today, though, and post the link. Otherwise I might just make it a 'show and tell'.

[facelessuser]

The experimental label was mainly expecting a number of opinions coming in about the syntax, but I am yet to hear anything negative about it. At some point, I'm going to remove the experimental status.

I have no idea how many people are actually using it compared to the existing indented approach. People often use what they are used to. I imagine there may be people just not aware of it either.

If you add examples, I would definitely note that people should not enable a legacy plugin with the new block plugin at the same time. Because they both have the same output, both plugins can sometimes step on each other's toes trying to process the content. If you have old style admonitions and new style block admonitions enabled, the new admonitions will see the new block syntax, but the old style will try to process the content under the block. It's just how the extensions work.

[StarfallProjects]

@alexvoss did the PR to support the new admonition syntax go live yet? Had a quick scan through recent release notes and can't spot what version it's in. I'd love to get us upgraded to this as we keep hitting blips in our admonition formatting.

[alexvoss]

I think my confusion comes from the fact the Material for MkDocs has different admonitions defined by default compared to what you have in the plugin. It has bug, for example, but not attention. For the example I am writing, it would seem best to advise people to just define the list of admonition types they want to use, which is what I have at the moment anyway. This is a bit of a difference compared to the traditional syntax but I think it is totally worth it.

[facelessuser]

Material is a user of pymdownx, pymdownx is not a Material library, we don't bias things for Material just because it is popular. The discussion I linked explains where the defaults come from, but not all people who use pymdownx are Material users.

[alexvoss]

Of course, I am just trying to figure out for myself what to write in the example, which is for Material. I am not suggesting what you should change anything. Apologies if I came across as trying to do that.

[facelessuser]

I would just state that the defaults do not accommodate all of Material's special types by default; therefore, if shorthand names are desired, those names must be registered and provide an example showing a configuration defining all Material types.

[facelessuser]

I think most people would want the short names for admonitions, so it may be a matter of just saying we need to define these because the defaults don't match Material's needs, and just offer the example as the recommended approach.