How to pass through custom tags?

[aviflax]

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.)

[robinst]

Hey! Yeah, so the problem is that the commonmark spec has a bit of a strict definition of what it considers HTML tags for blocks (link):

A tag name consists of an ASCII letter followed by zero or more ASCII letters, digits, or hyphens (-).

Note that there's no mention of : there. Also note that line breaks in the opening tag mean it's not recognized as a HTML block. But this works:

<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>
</structured-macro>

To be honest the : part is a bit of an oversight in the spec I think. I'll check if there's an existing issue for this, and raise one if not.

[robinst]

Ah look at this, opened 14 days ago :): commonmark/commonmark-spec#648

[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]

Oh that's a good idea :)!

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.

Yeah I understand.

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.

I'll close it. Whenever the spec gets updated they will include test case and when we update this library to a new version of the spec, we'll implement that. Even without test cases, I usually look through the spec changes.

[ioquatix]

It would be good if you can voice your support on the the linked issue on the spec.