This is a groovy script to import HTML files generated by asciidoctor to one or multiple Confluence pages.
-
splits large asciidoc documents in to several confluence pages. This is useful if you need to use the confluence comments for feedback
-
checks if pages need to be updated and only updates those in order to have a clean history and to avoid sending out unnecassary notifications
-
converts some asciidoc features to confluence macros (admonitions, code)
-
cleans up the asciidoc generated HTML to better fit the confluence storage format
-
displays errors from the confluence API
The easiest way to get this up and running is to modify the Config.groovy to fit your environment and load the main script into the groovyConsole. You then need some HTML output from asciidoctor (The arc42 template might be a good starting point, the HTML Sanity Checker Architecture Documentation is even better :-). Please note that the script is completely focussed on Asciidoctor output as it makes assumptions about the HTML structure (e.g. "sect1" and "sect2" css classes being present).
When you start the script the first time, it will try to split the html file into subsections and push them to your confluence instance. This is done to be able to handle large documentation pages and to be able to send update notifications for specific sections of a large document. This can be switched off though by the confluenceCreateSubpages configuration parameter.
The script can be run directly, via Maven or Gradle. It requires Java >= 7 and the scriptBasePath variable being set which points to the folder where to find the Config.groovy file.
The following pom.xml sample shows how to use the asciidoc2confluence.groovy script with your Maven build. It will run when you execute the mvn gplus:execute goal.
<?xml version="1.0" encoding="UTF-8"?>
<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>io.github.rdmueller</groupId>
<artifactId>asciidoc2confluence</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>jar</packaging>
<name>asciidoc2confluence sample</name>
<description>An asciidoc2confluence sample pom.xml</description>
<properties>
<!-- The following class will be used in the MANIFEST.MF -->
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<java.version>1.8</java.version>
<java.target.version>1.8</java.target.version>
<java.source.version>1.8</java.source.version>
</properties>
<build>
<finalName>${project.artifactId}</finalName>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<target>${java.target.version}</target>
<source>${java.source.version}</source>
</configuration>
</plugin>
<plugin>
<groupId>org.codehaus.gmavenplus</groupId>
<artifactId>gmavenplus-plugin</artifactId>
<version>1.5</version>
<executions>
<execution>
<goals>
<goal>execute</goal>
</goals>
</execution>
</executions>
<configuration>
<properties>
<property>
<name>scriptBasePath</name>
<value>${project.basedir}/src/main/groovy/</value>
</property>
</properties>
<scripts>
<script>file:///${project.basedir}/src/main/groovy/asciidoc2confluence.groovy</script>
</scripts>
</configuration>
<dependencies>
<dependency>
<groupId>org.codehaus.groovy</groupId>
<artifactId>groovy-all</artifactId>
<!-- any version of Groovy \>= 1.5.0 should work here -->
<version>2.4.3</version>
<scope>runtime</scope>
</dependency>
</dependencies>
</plugin>
</plugins>
</build>
</project>The following build.gradle sample shows how to use the asciidoc2confluence.groovy script with your Gradle build. It will run when you execute the gradle task gradlew publishToConfluence.
buildscript {
dependencies {
//for the exportJiraIssues Task
classpath 'org.codehaus.groovy.modules.http-builder:http-builder:0.6'
//for the renderToConfluence Task
classpath 'org.apache.httpcomponents:httpmime:4.3.1'
classpath 'org.jsoup:jsoup:1.9.1'
}
repositories {
jcenter()
}
}
task publishToConfluence(
description: 'publishes the HTML rendered output to confluence',
group: 'docToolchain'
) {
// Directory containing the documents to be processed by docToolchain.
// If the documents are together with docToolchain, this can be relative path.
// If the documents are outside of docToolchain, this must be absolute path, usually provided
// on the command line with -P option given to gradle.
def docDir = file('.').path
def confluenceConfigFile = "scripts/ConfluenceConfig.groovy"
def confluenceScript = project.file('scripts/asciidoc2confluence.groovy')
doLast {
binding.setProperty('docDir', docDir)
binding.setProperty('confluenceConfigFile', confluenceConfigFile)
evaluate(confluenceScript)
}
}