Option for custom templates

[masooh]

For better customization of the generated output we want to use our own Slim templates. Please provide an option to customize the template folder.

At the moment the template folder is hardcoded in AsciidocConfluenceConverter.java

private static final String TEMPLATE_ROOT_CLASS_PATH_LOCATION = "org/sahli/asciidoc/confluence/publisher/converter/templates";
// ...
URL templateRootUrl = AsciidocConfluencePage.class.getClassLoader().getResource(TEMPLATE_ROOT_CLASS_PATH_LOCATION);

[cstettler]

Hi @masooh, thank you for opening this ticket. What would be your need for customizing the Slim templates? In general, we try to keep the use of the Slim templates as an internal implementation detail, and not expose it for customization. For some features, there is a tight coupling between the markup generated by the Slim templates and the post-processing done by the code. This might break in case of Slim template customizations.

If we could better understand your need for customization, maybe there would be another way of supporting this customization.

[masooh]

Hi @cstettler, thank you for the feedback.

First use case is table of contents.

• The Links of the generated table of contents are broken, therefore we want to use the TOC makro, see also #87
• We want to make our TOC collapsible with the expand macro, probably realated to #157

Our block_toc.html.slim looks at the moment like this:

ac:structured-macro ac:name="expand" ac:schema-version="1"
  ac:parameter ac:name="title" Inhaltsverzeichnis
  ac:rich-text-body
    p
      ac:structured-macro ac:name="toc" ac:schema-version="1"
        ac:parameter ac:name="outline" true

So maybe this can be solved via the other mechanisms.

Second use case is the usage of the PlantUML render macro (https://avono-support.atlassian.net/wiki/spaces/PUML/pages/33816578/Macro+plantumlrender+and+flowchartrender):

At the moment plantuml diagrams are rendered by asciidoctor-diagram. We want the Confluence macro to do the rendering. Therefore we would have to change probably the block_listing.html.slim template.

[jaimecasero]

Im chasing same use case where plantuml macro is used instead of standard ac:image.

One way to do this is to use some Maven tricks to override the default templates. Most likely everyone is aware of such hack, but I'm sharing here just in case:

`

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.1nce</groupId> <artifactId>ng-platform</artifactId> 0.0.0-SNAPSHOT jar <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-jar-plugin</artifactId> 3.3.0 jar generate-sources **/*.slim <groupId>org.sahli.asciidoc.confluence.publisher</groupId> <artifactId>asciidoc-confluence-publisher-maven-plugin</artifactId> 0.21.0 publishDoc publish test <groupId>com.1nce</groupId> <artifactId>ng-platform</artifactId> 0.0.0-SNAPSHOT system <systemPath>${project.build.directory}/ng-platform-0.0.0-SNAPSHOT.jar</systemPath> <groupId>org.asciidoctor</groupId> <artifactId>asciidoctorj</artifactId> 2.5.10 compile <groupId>org.asciidoctor</groupId> <artifactId>asciidoctorj-diagram</artifactId> 2.2.9 compile <groupId>org.asciidoctor</groupId> <artifactId>asciidoctorj-chart</artifactId> 1.0.0 <asciidocRootFolder>./</asciidocRootFolder> <sourceEncoding>UTF-8</sourceEncoding> <rootConfluenceUrl>https://1ncegmbh.atlassian.net/wiki</rootConfluenceUrl> <skipSslVerification>false</skipSslVerification> <maxRequestsPerSecond>5</maxRequestsPerSecond> <spaceKey>${env.CONFLUENCE_SPACE}</spaceKey> <ancestorId>${env.CONFLUENCE_ANCESTOR}</ancestorId> ${env.CONFLUENCE_USER} ${env.CONFLUENCE_TOKEN} <pageTitlePrefix xml:space="preserve">NG </pageTitlePrefix> <pageTitleSuffix xml:space="preserve"></pageTitleSuffix> <versionMessage>Version ${env.VERSION_TAG}</versionMessage> <notifyWatchers>false</notifyWatchers> <orphanRemovalStrategy>KEEP_ORPHANS</orphanRemovalStrategy> <convertOnly>${env.CONVERT_ONLY}</convertOnly> `

With this pom, a local jar file will be generated with your custom templates under "src/main/resources". You need to copy paste the whole converter "org" directory, and make your changes there. Then the confluence publisher plugin is overridden with a system path pointing to generated jar file. I know this looks hacky and nasty, but it will work with minimal involvement (no separate maven project and deployment into server to resolve dependency) and works in any CI pipeline, since there is no hardcoded paths. If you want to reuse your templates in multiple projects, you can of course have a dedicated maven project generating the jar file and push it to your private artefact registry...