Introducing a way to transform divs to specific HTML elements

Help / Discuss
#1

There are cases where it would be handy to transform groups to specific HTML elements such as nav, aside, form and others. The need emerged for instance while discussing evolutions of the TOC macro. We would then need a syntax convention on when to trigger such a transformation, for example:

(% data-xwiki-html-element="aside" class="myaside" %)(((
* Item 1
* Item 2
)))

Which would render in HTML as:

<aside class="myaside">
<ul>
<li> Item 1
<li> Item 2
</ul>
</aside>

What do you think? Any other attribute name suggestion? Do you know about any Markdown extension targeting the same use case? Or do you see other approaches to generate such specific HTML elements?

Improving the HTML structure of TOC macro output
#2

If we add support for this during rendering, the parser will also need a handler for each of these elements to transform them back into the correct XDOM/XWiki syntax. Further, we need to ensure that these elements are also available in the WYSIWYG editor - we have a content filter with an explicitly allowed list of elements there. Otherwise, we’ll get all kinds of strange behavior when using the WYSIWYG editor. Alternatively, we could decide to render this attribute as-is in the annotated HTML renderer and only transform it into the correct tag in the regular HTML renderer - this will lead to visual differences in the WYSIWYG editor, though, which is probably also not desirable.

If we start this now, we also kind of establish that there won’t be specific blocks for these elements in the XDOM. I’m therefore not a fan of introducing this in a fully generic way. In particular, a fully generic implementation would also allow embedding SVG or MathML using this syntax which might not be what we intended. Instead, I suggest we make a list of specific HTML elements that are actually similar to a <div> in their behavior (in particular, allow the same parent and child tags) and implement rendering and parsing support for them by translating the attribute if the value is in the list of these HTML elements.

I’m not aware of any Markdown extensions for this use case, my understanding is that in Markdown the solution is usually to just embed plain HTML for this.

Another solution would be to have a macro for each element that just generates a raw HTML block or to introduce new XDOM blocks and rendering events that can be used by such macros.