How to add admonitions to an ordered list?

[vjmanda]

Adding admonitions to ordered list doesn't render properly if its indented under the the list item. Removing the indentation makes it render properly but it breaks the ordered list sequencing.

I am trying to do something like this.

1. Step one.

!!! info
    Some info.

1. Step two.

!!! info
    Some more info.

1. Step three.

1. Step four.

[squidfunk]

List item content must be indented by four spaces:

1. Step one.

    !!! info
        Some info.

1. Step two.

    !!! info
        Some more info.

[vjmanda]

List item content must be indented by four spaces:

1. Step one.

    !!! info
        Some info.

1. Step two.

    !!! info
        Some more info.

I agree but the admonitions don't render the blocks properly if you indent them. They show as plain text instead.

[squidfunk]

Make sure you have SuperFences enabled. The recommended configuration for using admonitions is:

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

[segfaultxavi]

I am encountering the same issue. No amount of indenting allows me to show the admonition when it's inside a list. It renders as plain text.

My source:

1. List item

    !!! info
        Help.

Renders as:

Versions from requirements.txt:

mkdocs==1.2.4
mkdocs-material==8.1.11
mkdocs-material-extensions==1.0.3
mkdocs-git-revision-date-plugin==0.3.1
mkdocs-autolinks-plugin==0.5.0
mkdocs-redirects==1.0.4
mdx-truly-sane-lists==1.2
jinja2==3.1

Relevant portion of mkdocs.yml:

theme:
  name: material
  custom_dir: docs/assets/overrides
  palette:
    scheme: default
  logo: assets/logo.png
  favicon: assets/favicon.png
  features:
    - navigation.tabs           # Top-level pages are shown as tabs on the header
    - navigation.tabs.sticky    # Navigation tabs are always visible
    - navigation.top            # "Back to top" button appears upon upward scrolling
    - navigation.indexes        # Allow section headers to have a page (see tech/index.md)
markdown_extensions:
  - admonition                  # Info boxes (in different colors)
  - pymdownx.details            # "
  - pymdownx.superfences        # Info boxes, tabs
  - pymdownx.caret              # Allow superscript and insertion marks (^ and ^^)
  - pymdownx.tilde              # Allow subscript and deletion marks (~ and ~~)
  - pymdownx.keys               # Allow Keyboard marks (++)
  - pymdownx.mark               # Allow selection marks (==)
  - pymdownx.inlinehilite       # Syntax-highlight inline code
  - pymdownx.tabbed:            # Tabbed content
      alternate_style: true
  - toc:                        # TOC control
      permalink: 🖈             # Add permalinks to headers
  - pymdownx.arithmatex:        # Math blocks
      generic: true
  - mdx_truly_sane_lists        # 2-space indented nested lists
  - attr_list                   # { Annotations }
  - md_in_html                  # Markdown inside HTML
  - def_list                    # Definition lists (Glossary)
plugins:
  - search                      # Search box at the top
  - git-revision-date           # Last edit timestamp at the bottom
  - autolinks                   # Use just filenames instead of full or relative paths

[segfaultxavi]

It figures, the moment I post the issue I find the culprit. The mdx_truly_sane_lists extension is interfering, and it's a known issue:

radude/mdx_truly_sane_lists#6

The suggested solution worked for me: use 2-space indents which is what mdx_truly_sane_lists sets as default.
(Incidentally, this renders my statement "No amount of indenting allows me to show the admonition when it's inside a list" utterly false. Apologies.)

[kamilk]

This helped me a lot. mdx_truly_sane_lists is one of the plugins included in Backstage Roadie TechDocs core plugins (https://github.com/backstage/mkdocs-techdocs-core), so this interference is very likely to occur.

[jtreher]

2-space indenting, unfortunately doesn't seem to be compatible with common markdown previews since 3 spaces are required for ordered lists. They get you coming and going.

[agithubusr]

🏅 thx ... am in the same boat with the TechDocs.

[rmartine-ias]

2-space indents isn't working for me. Can you provide a working snippet?

It's a fairly terrible solution, but you can do it with inline HTML:

1. Some List Item

   <!-- We use an HTML element because admonitions are not parsed if indented,
   and if it is unindented, it breaks list parsing (1, 1, 2...) and adds a
   margin to all following list items. -->

   <!-- markdownlint-disable MD033 -->
   <div class="admonition tip inline end">
   <p class="admonition-title">Tip</p>
       If Docker is not enabled, use <code>--no-docker</code> instead of
       <code>--docker-image</code>, and ensure the <code>venv</code> is activated.
   </div>
   <!-- markdownlint-enable MD033 -->

[facelessuser]

You can potentially try the Blocks extension and see if it plays better with sane lists. https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/admonition/

You can configure it to recognize all the material classes like so (ignore new and settings which are custom): https://github.com/facelessuser/pymdown-extensions/blob/main/mkdocs.yml#L174.

Now, I have not tried this yet with sane lists, but this is definitely something you can try and may have success with.

[rmartine-ias]

Thank you, I will look into this! I'm going to try this plugin as well, when I have a little time: https://github.com/oprypin/markdown-callouts

Something that is annoying about admonitions is that various markdown formatters aren't aware of them, so I have to use a bunch of <!-- prettier-ignore --> directives to avoid them being collapsed into a single line. I don't think your plugin improves over the normal syntax in that regard, but it does look very good for nesting... Will definitely check it out and compare.

[facelessuser]

Sure, that's fair. It's mainly about what adds the value you care most about. Callouts definitely has certain advantages.