Publish Your Docs to Confluence

There are times when you’ll want to publish your docs to Confluence, such as when you work in a team where not everyone wants to work with Git. docToolchain lets you publish your Git-based docs to Confluence alongside manually edited Confluence pages.

Another situation is when you want to work with the arc42 template in Confluence. There are several ways to import the template, but most of them require admin access. To get around this, you can set up a fresh copy of the arc42 template in docToolchain and publish it to your Confluence instance.

In this tutorial, you’ll learn how to publish the arc42 template to a Confluence cloud instance.

Step 1. Set Up docToolchain

If you have completed instructions install docToolchain and get the arc42 template you can skip this part.

For this tutorial, we assume that you work with a macOS/Linux-based system.

  1. In the Terminal, type the following:

    $ mkdir publishToConfluenceDemo
$ cd publishToConfluenceDemo
$ curl -Lo dtcw doctoolchain.org/dtcw
    Show output 
    gitpod /workspace/publishToConfluenceDemo (main) $ curl -Lo dtcw doctoolchain.org/dtcw
% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
Dload  Upload   Total   Spent    Left  Speed
100   162  100   162    0     0   1306      0 --:--:-- --:--:-- --:--:--  1317
100 10724  100 10724    0     0  25903      0 --:--:-- --:--:-- --:--:-- 25903

  2. Next, make the file dtcw executable.

    $ chmod +x dtcw

  3. If you do not have docToolchain as a Docker image, type

    $ ./dtcw getJava
    Show output 
    ./dtcw: line 28: !false: command not found
dtcw - docToolchain wrapper V0.31
docToolchain V2.0.5
docker available
this script assumes that you have linux as operating system (x64 / linux)
it now tries to install Java for you
downloading JDK Temurin 11 from adoptiom to /home/gitpod/.doctoolchain/jdk.tar.gz
WARNING: combining -O with -r or -p will mean that all downloaded content
will be placed in the single file you specified.

--2022-08-25 20:07:11--  https://api.adoptium.net/v3/binary/latest/11/ga/linux/x64/jdk/hotspot/normal/eclipse?project=jdk
Resolving api.adoptium.net (api.adoptium.net)... 20.62.244.126
Connecting to api.adoptium.net (api.adoptium.net)|20.62.244.126|:443... connected.
HTTP request sent, awaiting response... 307 Temporary Redirect
Location: https://github.com/adoptium/temurin11-binaries/releases/download/jdk-11.0.16.1%2B1/OpenJDK11U-jdk_x64_linux_hotspot_11.0.16.1_1.tar.gz [following]
--2022-08-25 20:07:12--  https://github.com/adoptium/temurin11-binaries/releases/download/jdk-11.0.16.1%2B1/OpenJDK11U-jdk_x64_linux_hotspot_11.0.16.1_1.tar.gz
Resolving github.com (github.com)... 140.82.121.3
Connecting to github.com (github.com)|140.82.121.3|:443... connected.
HTTP request sent, awaiting response... 302 Found
Location: https://objects.githubusercontent.com/github-production-release-asset-2e65be/372924883/70b80b22-3dc5-4824-bb2d-d0158a3b9b57?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIWNJYAX4CSVEH53A%2F20220825%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220825T200712Z&X-Amz-Expires=300&X-Amz-Signature=887a715fcbd2e2d6bf24496f57b168ba2204f0f81794a66615ab53a7b153ed37&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=372924883&response-content-disposition=attachment%3B%20filename%3DOpenJDK11U-jdk_x64_linux_hotspot_11.0.16.1_1.tar.gz&response-content-type=application%2Foctet-stream [following]
--2022-08-25 20:07:12--  https://objects.githubusercontent.com/github-production-release-asset-2e65be/372924883/70b80b22-3dc5-4824-bb2d-d0158a3b9b57?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIWNJYAX4CSVEH53A%2F20220825%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20220825T200712Z&X-Amz-Expires=300&X-Amz-Signature=887a715fcbd2e2d6bf24496f57b168ba2204f0f81794a66615ab53a7b153ed37&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=372924883&response-content-disposition=attachment%3B%20filename%3DOpenJDK11U-jdk_x64_linux_hotspot_11.0.16.1_1.tar.gz&response-content-type=application%2Foctet-stream
Resolving objects.githubusercontent.com (objects.githubusercontent.com)... 185.199.109.133, 185.199.111.133, 185.199.108.133, ...
Connecting to objects.githubusercontent.com (objects.githubusercontent.com)|185.199.109.133|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 193754645 (185M) [application/octet-stream]
Saving to: ‘/home/gitpod/.doctoolchain/jdk/jdk.tar.gz’

/home/gitpod/.doctoolchain/jdk 100%[====================================================>] 184.78M   310MB/s    in 0.6s

2022-08-25 20:07:13 (310 MB/s) - ‘/home/gitpod/.doctoolchain/jdk/jdk.tar.gz’ saved [193754645/193754645]

FINISHED --2022-08-25 20:07:13--
Total wall clock time: 1.7s
Downloaded: 1 files, 185M in 0.6s (310 MB/s)
expanding JDK

  4. Answer the questions that appear during installation.

    You will see lots of .jar files getting downloaded.

  5. Initialise docToolchain by running your first task.

    $ ./dtcw tasks
    Show output 
    dtcw - docToolchain wrapper V0.31
docToolchain V2.0.5
local java JDK found
use /home/gitpod/.doctoolchain/jdk as JDK

docker available
force use of local install
docToolchain not installed.
sdkman not found
Do you wish to install doctoolchain to /home/gitpod/.doctoolchain?
1) Yes
2) No
#? 1
installing doctoolchain
mkdir: cannot create directory ‘/home/gitpod/.doctoolchain’: File exists
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
100 1783k  100 1783k    0     0  2857k      0 --:--:-- --:--:-- --:--:-- 2857k
Archive:  /home/gitpod/.doctoolchain/source.zip
   creating: /home/gitpod/.doctoolchain/./docToolchain-2.0.5/
   creating: /home/gitpod/.doctoolchain/./docToolchain-2.0.5/bin/
  inflating: /home/gitpod/.doctoolchain/./docToolchain-2.0.5/bin/autobuildSite.bash
  inflating: /home/gitpod/.doctoolchain/./docToolchain-2.0.5/bin/doctoolchain

[152 lines omitted]

  inflating: /home/gitpod/.doctoolchain/./docToolchain-2.0.5/template_config/pdfTheme/custom-theme.yml
   creating: /home/gitpod/.doctoolchain/./docToolchain-2.0.5/resources/
   creating: /home/gitpod/.doctoolchain/./docToolchain-2.0.5/resources/asciidoctor-reveal.js/
   creating: /home/gitpod/.doctoolchain/./docToolchain-2.0.5/resources/reveal.js/
Picked up JAVA_TOOL_OPTIONS:  -Xmx3489m
Downloading https://services.gradle.org/distributions/gradle-6.9.2-bin.zip
..........10%..........20%..........30%...........40%..........50%..........60%..........70%...........80%..........90%..........100%

Welcome to Gradle 6.9.2!

Here are the highlights of this release:
 - This is a small backport release.
 - Java 16 can be used to compile when used with Java toolchains
 - Dynamic versions can be used within plugin declarations
 - Native support for Apple Silicon processors

For more details see https://docs.gradle.org/6.9.2/release-notes.html

To honour the JVM settings for this build a single-use Daemon process will be forked. See https://docs.gradle.org/6.9.2/userguide/gradle_daemon.html#sec:disabling_the_daemon.
Daemon will be stopped at the end of the build

> Configure project :

Config file '/workspace/publishToConfluenceDemo/docToolchainConfig.groovy' does not exist'
[ant:input]
[ant:input] do you want me to create a default one for you? (y, n)
<<-------------> 0% CONFIGURING [2m 55s]

> Task :help

Welcome to Gradle 6.9.2.

To run a build, run gradlew <task> ...

To see a list of available tasks, run gradlew tasks

To see a list of command-line options, run gradlew --help

To see more detail about a task, run gradlew help --task <task>

For troubleshooting, visit https://help.gradle.org

BUILD SUCCESSFUL in 3m 29s
1 actionable task: 1 executed

  6. Next download the arc42 template

    $ ./dtcw downloadTemplate
    Show output 
    dtcw - docToolchain wrapper V0.31
docToolchain V2.0.5
local java JDK found
use /home/gitpod/.doctoolchain/jdk as JDK

docker available
home folder exists
use local homefolder install /home/gitpod/.doctoolchain/
Picked up JAVA_TOOL_OPTIONS:  -Xmx3489m
To honour the JVM settings for this build a single-use Daemon process will be forked. See https://docs.gradle.org/6.9.2/userguide/gradle_daemon.html#sec:disabling_the_daemon.
Daemon will be stopped at the end of the build

> Task :downloadTemplate
Install arc42 documentation template.
For more information about arc42 see https://arc42.org
[ant:input] Which language do you want to install? (EN, DE, ES, RU)
<-<-------------> 0% EXECUTING [11s]
[ant:input] Do you want the template with or without help? (withhelp, plain)
<-<<-<--<-------------> 0% EXECUTING [17s]
Download https://github.com/arc42/arc42-template/raw/master/dist/arc42-template-EN-withhelp-asciidoc.zip
arc42 template unpacked into /workspace/publishToConfluenceDemo/src/docs/arc42
added template to docToolchainConfig.groovy
use 'generateHTML', 'generatePDF' or  'generateSite' to convert the template

BUILD SUCCESSFUL in 22s
1 actionable task: 1 executed

    You should now have the following folder structure in your project:

    Project Folder Structure
    .
├── docToolchainConfig.groovy
├── dtcw
└── src
└── docs
├── arc42
│   ├── arc42.adoc
│   └── chapters
│       ├── 01_introduction_and_goals.adoc
│       ├── 02_architecture_constraints.adoc
│       ├── 03_system_scope_and_context.adoc
│       ├── 04_solution_strategy.adoc
│       ├── 05_building_block_view.adoc
│       ├── 06_runtime_view.adoc
│       ├── 07_deployment_view.adoc
│       ├── 08_concepts.adoc
│       ├── 09_architecture_decisions.adoc
│       ├── 10_quality_requirements.adoc
│       ├── 11_technical_risks.adoc
│       ├── 12_glossary.adoc
│       ├── about-arc42.adoc
│       └── config.adoc
└── images
├── 01_2_iso-25010-topics-EN.png
├── 05_building_blocks-EN.png
├── 08-Crosscutting-Concepts-Structure-EN.png
└── arc42-logo.png

5 directories, 21 files

Step 2. Configure Publication to Confluence

To configure authentication through the Confluence API, do the following.

  1. In the root of your project foler, open the file docToolchainConfig.groovy.

  2. Find the text confluence.with.

    This is the start of the section where you configure publication to Confluence. As you can see, docToolchain is preconfigured to publish sample input (the arc42 template) to Confluence. The input for the publishToConfluence task is the output of the generateHTML task. You should see this:

    input = [
    [ file: "build/html5/arc42/arc42.html" ],
]

  3. Set up the API endpoint. Get your Atlassian Confluence URL, such as https://arc42-template.atlassian.net.

    Endpoint Syntax
    api = 'https://[yourServer]/[context]'

    In this case, the correct endpoint is https://arc42-template.atlassian.net/wiki.

    The context is optional, unless it is something other that "wiki". If you would like to enforce a URL that has no context (only valid if you specified useV1Api = true) for Confluence Server you should specify the full API URL, like https://confluence.example.com/rest/api.

  4. In docToolchainConfig.groovy, add the space-key, such as 8FE.

    spaceKey = '8FE'

Step 2.1. Configure Confluence Authentication

Step 2.1a. CLI Authentication with username and password (insecure)
This method is not recommended. Instead of passing your password, you can use a Personal Access Token, which can easily be revoked on the event of a compromise. See Authentication with Personal Access Token.

In the Terminal, type the following:

$ ./dtcw publishToConfluence -PconfluenceUser=<your username> -PconfluencePass=<your password>
Step 2.1b: CLI Authentication with username and API token
This method only works for Confluence Cloud. I can use an API token. The key has to be generated from the central Atlassian account.

  1. Navigate to your central Atlassian profile.

    070 first

  2. Go to Manage your Account.

    070 second

  3. Click Security > API token > Create and manage API tokens.

    070 third
    Here is the shortcut to this page.

  4. Now, click Create API token.

  5. Store your API token in a safe location.

  6. Add your API token e-mail address as username and password to the ./dtcw command.

    $ ./dtcw publishToConfluence -PconfluenceUser=<your email> -PconfluencePass=<your api-token>
Step 2.1c: CLI Authentication with Personal Access Token

If you do not want to pass your password and you are not an admin of your Confluence instance, you can use a Personal Access Token (PAT). Follow the Confluence documentation to generate one.

In the Terminal, type the following to publish to Confluence with your PAT:

$ ./dtcw publishToConfluence -PconfluenceBearerToken=<your personal access token>

Step 3: Verify Your Configuration

To verify your configuration execute ./dtcw verifyConfluenceApiAccess and pass the credentials to the task, depending on the setup you chose in the steps before. An example would be

$ ./dtcw verifyConfluenceApiAccess -PconfluenceUser=<your email> -PconfluencePass=<your api-token>

If the API is accessible, the task will succeed and print the API version that is used. Otherwise, an error will be printed.

...
Daemon will be stopped at the end of the build

> Task :verifyConfluenceApiAccess
Using Confluence API V1

BUILD SUCCESSFUL in 15s
3 actionable tasks: 3 executed

Step 4: Publish Your Pages

To publish your pages to Confluence, type:

$ ./dtcw publishToConfluence <extra arguments>
Show output 
dtcw - docToolchain wrapper V0.31
docToolchain V2.0.5
local java JDK found
use /home/gitpod/.doctoolchain/jdk as JDK

docker available
home folder exists
use local homefolder install /home/gitpod/.doctoolchain/
Picked up JAVA_TOOL_OPTIONS:  -Xmx3489m
To honour the JVM settings for this build a single-use Daemon process will be forked. See https://docs.gradle.org/6.9.2/userguide/gradle_daemon.html#sec:disabling_the_daemon.
Daemon will be stopped at the end of the build

> Task :publishToConfluence
publish /workspace/publishToConfluenceDemo/build/html5/arc42/arc42.html
arc42
Start getting headers
> created page 2033844225
1. Introduction and Goals
Start getting headers
    image: ../images/01_2_iso-25010-topics-EN.png
allPages already retrieved
> created page 2033909761
Start getting headers
2. Architecture Constraints
Start getting headers
allPages already retrieved
> created page 2033975297
3. System Scope and Context
Start getting headers
allPages already retrieved
> created page 2034008065
4. Solution Strategy
Start getting headers
allPages already retrieved
> created page 2034040833
5. Building Block View
Start getting headers
    image: ../images/05_building_blocks-EN.png
allPages already retrieved
> created page 2034073601
Start getting headers
6. Runtime View
Start getting headers
allPages already retrieved
> created page 2034139137
7. Deployment View
Start getting headers
allPages already retrieved
> created page 2034106374
8. Cross-cutting Concepts
Start getting headers
    image: ../images/08-Crosscutting-Concepts-Structure-EN.png
allPages already retrieved
> created page 2034139152
Start getting headers
9. Architecture Decisions
Start getting headers
allPages already retrieved
> created page 2034040848
10. Quality Requirements
Start getting headers

This command will first run the task generateHTML and then create one Confluence page for each arc42-chapter.

070 fourth