Further refinements for Confluence specific HTML

[aheusingfeld]

There are some parts of the HTML that look very different in Confluence.

• replace :toc: with <p><ac:structured-macro ac:name="toc"/></p>
• replace Note with <ac:structured-macro ac:name="info"><ac:rich-text-body><p>${body}</p></ac:rich-text-body></ac:structured-macro>
• replace <code> with <ac:structured-macro ac:name="code"><ac:plain-text-body><![CDATA[${body}]]></ac:plain-text-body></ac:structured-macro>

Feedback welcome

[rdmueller]

some problems with :toc: ...

1. ... asciidoc currently renders the :toc: in the preamble section which is currently not posted to confluence... but this could be fixed
2. afaik, the toc macro only renders the toc for one page - so in only makes sense if confluenceCreateSubpages = false, but it doesn't harm for subpages since it just displays nothing in this case... . So it wouldn't be a replacement, but an insertion for each page, right?
3. for confluenceCreateSubpages = true, the script already adds the children macro to the end of each page.

=> I will now add the toc macro to the start of each page

[rdmueller]

note works fine. Also added special handling for the arc42help sections.

How can we render the other admonitions like warn?

[aheusingfeld]

To be honest, I guess we have 2 options here:

1. We go forward with the current approach (modify generated HTML so it fits Confluence) and are therefore able to handle other input than asciidoc as parsing and conversion can be extracted into a separate Groovy file (parseBody() function) or
2. we take asciidoc input files and use asciidoctor (e.g. the Gradle or Maven plugin) with a Confluence backend that we will have to write - based on the existing HTML5 backend

Personally I'd vote for option 2 because I love asciidoc, but it's your choice and I know some colleagues who'd love to see option 1 and Markdown support.

[rdmueller]

option 1 is IMHO currently the easier, option 2 the cleaner and better way. I don't mind to drop my code/project for a cleaner working solution. Until then, I guess it makes sense to refine option 1.

Can you give me more details about "I know some colleagues who'd love to see option 1 and Markdown support" - maybe in another issue? The arc42-template project already contains code for converting asciidoc output to markdown via pandoc, so this might be a simple task.

[rdmueller]

I guess we should try merge https://github.com/gscheibel/asciidoctor-confluence and our project into one...

[aheusingfeld]

As I said in the comment above, IMO this project has a different scope than gscheibel's version - and I personally like it. So, I'm definitely a bit biased when I say, I'd like to keep it as it is or move it into the direction of variant 1 mentioned above. The point is that the script is named asciidoc2confluence though it actually takes "Asciidoctor created HTML" as an input. An alternative input could be Markdown generated HTML, I'd say.

[rdmueller]

OK. I do agree. Alternative input sounds good, but currently I want to get this script "feature complete". This mainly includes pushing images to confluence.

Regarding the name - we could add the the asciidoctor conversion or rename it to "asciidocHtml2confluence" for the time beeing. But for me, that's not too important. For me, it is more important to clean up the interface a bit and maybe create an artifact which could be pushed to a maven repository for ease of use...

[aheusingfeld]

currently I want to get this script "feature complete"

Couldn't agree more. Let's focus on #2, #7 and #6 first and bring out a release that can be used with Maven and gradle. That'll already be a huge next step, I'd say. I'd volunteer to take over #6, would that help you?

[rdmueller]

#6 would be very helpful since I've no experience with it... I am already working on #2 . Thanx!