Compatibility with mkdocs-material admonition extension

[Chris Alfano]

When used in combination with mkdocs-material's admonition extension it seems to become impossible to use admonitions within lists:

# Quickstart

## Bare-bones startup

1. Install [Docker Engine](https://docs.docker.com/engine/install/)
2. Clone private source repository from GitHub:

    ```bash
    git clone https://github.com/my-org/private-repo
    ```

    !!! tip
        These same steps can be applied to the public upstream repository: [`other-org/public-repo`](https://github.com/other-org/public-repo)

3. Change into the cloned source repository:

    ```bash
    cd ./private-repo/
    ```

The fenced code blocks however work fine

[Brennan Kinney]

It's not a third-party extension is it? Seems to be an official one.

[Brennan Kinney]

I investigated this. The issue is that admonition syntax is very sensitive to indentation level being correct. Regular inline content like paragraph text can start from the nested indent level, and go up to 3 more spaces of padding until being converted into an indented code block.

As the admonition syntax doesn't seem to support this by removing any additional white-space padding from the nested indent level, it fails to render. If you need to have that resolved, perhaps file a bug for it upstream on the python markdown parser (as it's not specifically mkdocs or the material theme nor this extension causing the issue afaik.

To resolve the main issue and have the admonition render correctly, use an indentation of 2 spaces which this extension sets as a default. Otherwise, for 4 spaces, you need to change the default nesting level in your mkdocs.yml:

markdown_extensions:
  - mdx_truly_sane_lists:
      nested_indent: 4

Your example will render correctly then.

[Brennan Kinney]

I have given this extension a try a bit and not seeing any notable improvement with mkdocs-material that you're using. As it's not been updated since 2018, the issues may have been fixed upstream.

With that said, this is an extension for markdown parsing iirc, not specifically mkdocs? (so if upstreams I mention resolved it, it may still affect others if it wasn't fixed in Python Markdown parser).

---

The only notable difference is that it can avoid merging separate lists, but usually your lists are likely to be kept separate via content in-between them. If you have lists with multi-line nested content, this can result in a single list being split into multiple lists accidentally as a result which may be more likely to happen.

Beyond that, you can benefit from 2 space indentation instead of 4 space indentation, but as this doesn't adjust indentation for other syntax such as admonition, there is not much point, so you would configure the indentation back to 4 like above.

It does remove the <p> tags like the README example shows too though which can be nice, but with mkdocs-material doesn't appear to make any visual difference.

---

The extension does not resolve rendering issues such as:

- a

    x

    - b
    - c
- d

Which at least with mkdocs-material you will find treats d as a child of a, and if your list is starting already indented, c can additionally become a child of b. To resolve it requires adding a blank line before c and d.

This doesn't require the x paragraph content, just a blank line after a before b, but is an issue can you can run into with nested lists and multi-line content in list items.

[Oleh Prypin]

Instead of the indentation-sensitive admonition syntax, consider this other extension that produces the same markup that also works with Material theme:
https://github.com/oprypin/markdown-callouts