How to pass through custom tags?

Hi, I’m attempting to render some Markdown documents that often include custom HTML tags, for example a tag like ac:structured-macro when a document is going to be published to a Confluence site.

With the simple, naïve, vanilla conversion that I’ve implemented so far, the custom tags are escaped in the output.

For example:

<ac:structured-macro ac:name="include"
                          ac:schema-version="1"
                          ac:macro-id="fbad7a5b-35fa-4d13-87ed-953ffd4dc456">
       <ac:parameter ac:name="">
         <ac:link><ri:page ri:content-title="mt" /></ac:link>
       </ac:parameter>
     </ac:structured-macro>

is being rendered as

<p>&lt;ac:structured-macro ac:name=&quot;include&quot;
ac:schema-version=&quot;1&quot;
ac:macro-id=&quot;fbad7a5b-35fa-4d13-87ed-953ffd4dc456&quot;&gt;
&lt;ac:parameter ac:name=&quot;&quot;&gt;
<a href="ac:link">ac:link</a>&lt;ri:page ri:content-title=&quot;mt&quot; /&gt;&lt;/ac:link&gt;
&lt;/ac:parameter&gt;
&lt;/ac:structured-macro&gt;</p>

I perused the docs, including the Javadocs, but didn’t see much that seemed directly relevant to this. (I did notice HtmlRenderer.Builder.escapeHtml() but I’m not calling that method, so the default, false should be in effect.)

Is there a way to do this?

Thank you!

(I’m using 0.15.0 on AdoptOpenJDK 13.0.2+8 on an AMD64 machine running MacOS 10.15.5.)

[aviflax]

Thanks @robinst! I really appreciate your thorough and clear response.

It seems like the best course of action here, in terms of this library, is to wait and see if/when the spec is updated to account for this.

I can live with that, especially because I’ve worked out a workaround. I stumbled across section 4.6 of the spec, on HTML Blocks. While reading that it occurred to me that if I could wrap my “custom” namespaced XHTML tags with section tags, that would mean they’d be part of an HTML block, and the spec says:

An HTML block is a group of lines that is treated as raw HTML (and will not be escaped in HTML output).

So I thought that might work. My tests show that yes, the approach should work as I thought, but I encountered another complication: the end condition for variants 6 and 7 is that a “line is followed by a blank line.” Some of my content had blank lines, so I was stymied, but it was only temporary — I rigged up a way to remove blank lines from my content.

So I’m good, for now.

That said, I’d rather not have to remove blank lines, or worry about them at all, so I do hope that at some point I’ll be able to pass namespaced “custom” tags through without worrying about all this.

Feel free to close this issue if you’d like, the only reason I’m not doing so is because I thought maybe you’d want to keep it open as a reminder to keep an eye on that spec discussion.

Thank you!

[robinst]

Ah look at this, opened 14 days ago 😃: https://github.com/commonmark/commonmark-spec/pull/648