Admonition: generate <details> with ???

[randomstuff]

Context

The admonition module supports ??? and ???+ for collapsible admonitions. This is inspired by mkdocs-material.

In this case, mdit-py-plugins generates:

<div class="admonition note is-collapsible collapsible-closed">
  <div class="admonition-title"></div>
</div>
<div class="admonition note is-collapsible collapsible-open">
    <div class="admonition-title"></div>
</div>

On the other hand, mkdocs-material generates:

<details class="note">
  <summary></summary>
</detail>
<details class="note" open="open">
    <summary></summary>
</detail>

Proposal

It should be possible to generate <details> and <summary> using ??? and ???+. An option should be provided to opt-in the new behavior (or bring back the current one).

Tasks and updates

• Add option for implementing ??? with details and summary

[KyleKing]

I'm chiming in as the main contributor to the admonition plugin. For context, the admonition plugin was ported from https://www.npmjs.com/package/markdown-it-admon, which generates HTML consistent with the markdown library (https://python-markdown.github.io/extensions/admonition/#syntax). If there were to be changes to the HTML output, they would likely better belong in the https://github.com/KyleKing/mdformat-mkdocs package, which handles mkdocs-specific formatting differences (like 4-spaces) in markdown and could be extended to modify the HTML output as well.

Could you describe how you are using the generated HTML? Could you link to an example repository where this is an issue? Having a better understanding of your use case will help inform the necessary changes.

[randomstuff]

If there were to be changes to the HTML output, they would likely better belong in the https://github.com/KyleKing/mdformat-mkdocs package, which handles mkdocs-specific formatting differences (like 4-spaces) in markdown and could be extended to modify the HTML output as well.

I'm not sure I'm following you. Isn't the mdformat-mkdocs about reformating .md files? Whereas we are talking about generating HTML form markdown here?

Could you describe how you are using the generated HTML? Could you link to an example repository where this is an issue?

This just feels nice to be able to generate <details> when using the ??? syntax as it appears to be semantically correct to use <details> for collapsible blocks.

Actually, the documentation explicitly references mkdocs-material as an inspiration for collapsible blocks which actually renders ??? as <details>.

[KyleKing]

If there were to be changes to the HTML output, they would likely better belong in the KyleKing/mdformat-mkdocs package, which handles mkdocs-specific formatting differences (like 4-spaces) in markdown and could be extended to modify the HTML output as well.

I'm not sure I'm following you. Isn't the mdformat-mkdocs about reformating .md files? Whereas we are talking about generating HTML from markdown here?

Could you describe how you are using the generated HTML? Could you link to an example repository where this is an issue?

This just feels nice to be able to generate <details> when using the ??? syntax as it appears to be semantically correct to use <details> for collapsible blocks.

Yeah, that's what I was getting at with that question. What's the value in modifying the HTML formatting logic within mdit-py-plugins if it isn't rendered?

Actually, the documentation explicitly references mkdocs-material as an inspiration for collapsible blocks which actually renders ??? as <details>.

Yeah, I made that change earlier this year and we had a discussion about the right HTML before settling on the minimum set of changes from the ported plugin: #58 (comment).

The clean code approach would have been to restrict mdit-py-plugins to the !!! syntax and then support variations in different packages (e.g. mdformat-mkdocs, mdformat-Obsidian-admonitions, mdformat-github-admonitions, etc.), but the logic is very hard to extend without reimplementing the same loops and adding package maintenance and versioning overhead, so adding the mkdocs markers seemed like an acceptable violation of the design principles (see KyleKing/mdformat-admon#4 (comment) and #58 (comment)). I would be hesitant to add more complexity though, although you're welcome to propose changes and I can review, but I'm not sure when they would be merged because I'm not a maintainer

[randomstuff]

Yeah, that's what I was getting at with that question. What's the value in modifying the HTML formatting logic within mdit-py-plugins if it isn't rendered?

🤔 I think there is a misunderstanding somewhere but I am not sure exactly why. I believe you are considering the feature in the context of the usage within mdformat whereas I am actually talking about the feature without any relation with mdformat.

My immediate use case would be to use ??? to render <details> in posts such as this one (this uses a custom static website generator). This can actually be implemented by post-processing the HTML (converting <div class="admonition warning is-collapsible collapsible-open"> into <details class="admonition warning" open> and so on). However, this could be more conveniently be provided to other users of the library byt implementing this feature in the library.

Existing code I'm using to post-process HTML

@lru_cache(maxsize=1024)
def render_markdown(source, base, method="html"):

    res = markdown_it_render.render(source)

    root = HTML(res)

    # Resolve relative links:
    for a in root.cssselect('a[href]'):
        a.set("href", process_link(base, a.get("href")))
    for img in root.cssselect('img[src]'):
        img.set("src", process_link(base, img.get("src")))
    for img in root.cssselect('img[longdesc]'):
        img.set("longdesc", process_link(base, img.get("longdesc")))
    for object in root.cssselect('object[data]'):
        object.set("data", process_link(base, object.get("data")))

    # I'm using 'p.table-caption' as a 'caption' element for the following table.
    # This is to work around the fact that the Table extensions apparently
    # does not allow setting attributes to table.
    for p in root.cssselect('p.table-caption'):
        del p.attrib["class"]
        p.tag = "caption"
        target = p.getnext()
        target.insert(0, p)

    # Accessibility for footnotes:
    for e in root.cssselect(".footnotes"):
        e.set("role", "group")
        e.set("aria-label", "Foot notes")
    for e in root.cssselect("a.footnote-item"):
        div.set("role", "note")
    for a in root.cssselect(".footnote-ref a"):
        a.set("aria-label", "(see note " + a.text + ")")
    for a in root.cssselect("a.footnote-backref"):
        a.set("aria-label", "back to main content")

    # Accessibility for admonition:
    for div in root.cssselect("div.admonition"):
        div.set("role", "note")
    for div in root.cssselect("p.admonition-title"):
        div.set("role", "heading")
        div.set("aria-level", "6")

    # Automatically compute figure id:
    for figure in root.cssselect('figure'):
        if figure.get("id") is not None:
            continue
        imgs = figure.cssselect('img')
        if len(imgs) != 1:
            continue
        src = imgs[0].get("src")
        if src is None:
            continue
        figure.set("id", "figure-" + Path(src).stem)

    # Build a TOC:
    body = root.find("body")
    for i, node in enumerate(body):
        if node.tag == "toc":
            toc = make_toc(body)
            body[i] = toc
            break

    return "".join(
                tostring(x, encoding="UTF-8", method=method).decode("UTF-8")
                for x in root.find("body")
            )

[KyleKing]

Ok! That example is really helpful and I think we both are on the same page

Historically, I don't think there is an example of a mdformat plugin that also supports HTML rendering, but this is a good use case and there is no reason that a package like mdformat-mkdocs couldn't do both. Let me put together an example

I've started working on support for MKDocs Material Content Tabs, which are really admonitions with a twist, so I'm thinking about how I could refactor the existing admon plugin for better extensibility.

[KyleKing]

Alright, I put together a quick POC here: https://github.com/KyleKing/mdformat-mkdocs/pull/15/files#diff-ec05f310f35726433b991f625a321e7dd02740abb830573859d423e979519a97

In your example, sometime before res = markdown_it_render.render(source) you would need to have markdown_it_render.use(admon_mkdocs_plugin) to have the desired output

I'll have more time over January to refactor and make the admon plugin more extensible (would be required to support other implementations like Obsidian, Github, MKDocs Content Tabs, etc.)

[KyleKing]

Okay, so I think I'm happy with the refactoring and the releases would be stable now, but I'm blocked by the pending release of mdformat-gfm, which pins an older version of mdit-py-plugins. See: hukkin/mdformat-gfm#31

For now, you give the HTML output a try by using a git checkout:

pip install mdformat-mkdocs@git+https://github.com/KyleKing/mdformat-mkdocs.git

See the example in the README: https://github.com/KyleKing/mdformat-mkdocs#html-rendering

Let me know if that resolves the original issue. Feel free to open new issues on my repo

FYI: I created #102

[KyleKing]

You can now install 'mdformat-mkdocs==2.0.1' which no longer need pip+git workarounds! And has a number of major improvements from new edge cases

[randomstuff]

Great, I'll look at that in the following days 🎊