Possible to modify Details extension to accept Markdown header syntax?

[NickC5163]

Hey folks,

Is it possible to modify the behavior of the Details extension so the first line (collapsible section header) can be inserted using Markdown header syntax?

For example, can I configure the parser to convert this:

??? ## Accordion header
    
    Content

To this:

<details><summary><h2>Accordion header</h2></summary><p>Content</p></details>

Ideally for h2s to h5s.

I'm not an expert in Python (basic understanding), so please try to ELI5 what code I can copy and paste into the details.py file.

I have tried messing around with it a bit by coping code from the section of the Markdown BlockProcessor that processer headers, to no avail :(

Thanks in advance.

[facelessuser]

I think what you are requesting is for something where an ID can be added to a Details element: #1194.

With that said, I have not yet decided upon or added such functionality, but if you follow the link, I offer some suggestions, such as wrapping the details with a <div id="some-id" markdown>.

If you must specifically have a header embedded within the summary, you will have to use raw HTML to accomplish the task. While, if I recall correctly, details may allow for inline Markdown, it will not recognize block-level syntax such as headers.

[NickC5163]

Thanks a lot for the reply. Might not be worth the effort. I'll stick to using HTML header tags for those portions of text.

[waylan]

I think I might have a good argument for adding this feature (or some variation of it). With various common search tools, the on-site search displays the header of the section which contains the search term. In some situations, it would be desirable for the <summary> to be displayed in the search results.

For example, consider this FAQs section:

# Frequently Asked Questions

/// details  |  What does "foo" mean?
"Foo" is placeholder text often used in code examples.

Currently, searching for the term "foo" would return a result:

Frequently Asked Questions

But if the summary contains a heading element (perhaps an <h2>), then the search result would be:

What does "foo" mean?

Obviously, that is more meaningful. Yes, an ID can be set on the detail in some other way (via attrs: id), but that doesn't change the way search displays the result.

I should note that heading elements (h1-6) are valid content in summary elements. The spec specifically mentions "heading content."

Yes, one can manually use raw tags, but in my testing, for search to show the heading, it needs to also have an ID set. And with raw HTML, we lose Markdown's ability to automatically generate an ID (with the appropriate extension). Therefore, it would be nice to be able to have Markdown create the heading elements for us.

Currently, Markdown considers summary to not be a block-level tag and I would say that is correct. As the only block level elements allowed within a summary are heading elements, it is correct to disallow all other block-level tags. Because of that, I don't think there is a practical way to allow parsing of /// details | ## What does "foo" mean? the way that the Markdown parser is currently implemented. Instead, I would suggest adding support for an additional block option: h-level. The option should accept values 0-1 where 0 (the default) results in no heading element (current behavior) and 1-6 results in the contents being wrapped in a heading element (h1-6).

/// details  |  What does "foo" mean?
    h-level: 2
"Foo" is placeholder text often used in code examples.

The above should generate the following HTML (assuming a compatible extension was enabled to auto-generate IDs:

<details>
<summary><h2 id="what-does-foo-mean">What does "foo" mean?</h2></summary>
<p>"Foo" is placeholder text often used in code examples.</p>
</details>

Thoughts?

As an aside, using details for FAQs are more practical now that they can work as exclusive accordians in most browsers. As the details block already allows defining the name attribute via attrs, there is no additional work to do on the extension (although, adding a group top-level option might be a nice shortcut). But for search, I would like to both display the specific question in the results and then jump directly to it upon selection. That requires headings in summaries.

[waylan]

For completeness, there are two potential issues that may need to be addressed as highlighted in Mozilla's developer docs for the summary element.

1. There is some weird whitespace behavior by default. At a minimum the following CSS needs to be defined summary h2 { margin: 0;}.
2. Assistive technologies such as screen readers may fail to recognize the heading role of headings within summaries. I don't think this is an issue here as that is the current behavior anyway (no heading role within summaries).

[facelessuser]

It's possible we could allow something like this, but we'd likely just special-case header logic within these blocks.

There is some weird whitespace behavior by default. At a minimum the following CSS needs to be defined summary h2 { margin: 0;}.

If we added this, we would likely not add any CSS directly to headers and just note it for users to add themselves.

Assistive technologies such as screen readers may fail to recognize the heading role of headings within summaries. I don't think this is an issue here as that is the current behavior anyway (no heading role within summaries).

Lastly, as far as assistive technology is concerned, unless someone notes a clear path forward for such issues, I would just ignore them until some future time when there is a known workaround.

[waylan]

It's possible we could allow something like this, but we'd likely just special-case header logic within these blocks.

That works too. I'll be playing with this and I'll see what solution I come up with.

There is some weird whitespace behavior by default. At a minimum the following CSS needs to be defined summary h2 { margin: 0;}.

If we added this, we would likely not add any CSS directly to headers and just note it for users to add themselves.

Obviously. Sorry if I wasn't clear about that.

[facelessuser]

I think there was a comment that got removed, but I wanted to address the thought for others who might be curious. I had noted we could special-case headers, and some may wonder why we wouldn't just send that content through the block processors?

Well, we could, and that may generate summary > p opposed to summary, which would be a change, and though that is likely fine, it would also open the door for some weird cases like the start of a list in the summary, nested detail starting in a details, some other weird cases I haven't thought about.

There are likely some edge cases I would miss, and there are very few cases I can think of that we'd want to specifically include outside of headers. Special casing headers keeps things simple.

That's just my initial hesitations. I would have to explore. It may be that using the block parser on the summary isn't a big deal; I'd just have to evaluate it.

[waylan]

Yeah, I deleted my comment because I realized those concerns existed and was able to come up with a working solution (which avoids them) with little difficulty. See #2917.