Asciidoctor-confluence is a ruby gem that takes Asciidoc files, parse them using Asciidoctor and push the result into Confluence.
This gem currently supports Asciidoctor 1.5.2
This gem supports Asciidoctor-Diagram 1.5.2
This gem is compatible with Confluence 5.x
First you need to download and install the gem
gem install asciidoctor-confluence
For local install from source, run from directory
gem build asciidoctor-confluence.gemspec
gem install --local asciidoctor-confluence
Then to create a page, decide title and run
asciidoctor-confluence \
--host HOST \
--spaceKey SPACE_KEY \
--title TITLE \
--username USERNAME \
--password PASSWORD \
--what page \
file.adoc
To update a page
asciidoctor-confluence \
--host HOST \
--spaceKey SPACE_KEY \
--title TITLE \
--pageid PAGEID \
--username USERNAME \
--password PASSWORD \
--what page \
--update \
file.adoc
It supports asciidoctor-diagram, so sections with plantUML diagrams will be compiled.
The created page will refer to attachments, so after loading a page with image, it is mandatory to upload images in order to see them.
To upload/update images
asciidoctor-confluence \
--host HOST \
--spaceKey SPACE_KEY \
--title TITLE \
--pageid PAGEID \
--username USERNAME \
--password PASSWORD \
--images images,path,list,separated,by,comma \
--what images
Here is the list of arguments that can used with this gem
Argument | Is mandatory | Role | Example |
---|---|---|---|
what |
yes |
Indicates the type of update. To be set to 'page' in this case |
page |
host |
yes |
The hostname of the Confluence instance |
|
spaceKey |
yes |
The space wihtin the page will be created |
|
title |
yes |
The title of the Confluence page |
|
username |
no |
The username to use if the page has write restrictions |
|
password |
no |
The password associated to the account used to login into Confluence |
|
update |
false |
Indicate that the page must be updated instead of created. No values are required for this option |
|
pageid |
no |
The ID of the page you want to update, if it’s not provided it will be determined using the space key and the title |
Here is the list of arguments that can used with this gem
Argument | Is mandatory | Role | Example |
---|---|---|---|
what |
yes |
Indicates the type of update. To be set to 'images' in this case |
images |
host |
yes |
The hostname of the Confluence instance |
|
spaceKey |
yes |
The space wihtin the page will be created |
|
title |
yes |
The title of the Confluence page |
|
username |
no |
The username to use if the page has write restrictions |
|
password |
no |
The password associated to the account used to login into Confluence |
|
images |
yes |
It is the list of paths of images to be uploaded as attachments |
image1.png,image2.png,build/image3.png |
pageid |
no |
The ID of the page you want to update, if it’s not provided it will be determined using the space key and the title |
If you want to try asciidoctor-confluence you can either download the gem:
gem install asciidoctor-confluence
Or install from the source
-
Install the gem locally (at the moment it has not been publish to rubygem)
-
Clone the github repository locally
git clone https://github.com/francescobonesi/asciidoctor-confluence.git
-
Built it
gem build asciidoctor-confluence.gemspec
-
Install it
gem install ./asciidoctor-confluence.0.0.3-SNAPSHOT.gem
-
To check it has been done correctly
asciidoctor-confluence -v
should displayasciidoctor-confluence: 0.0.3-SNAPSHOT
-
-
Have a Confluence instance
-
If you don’t have a Confluence server, you can use a Docker container (e.i.: https://registry.hub.docker.com/u/cptactionhank/atlassian-confluence/), the option requires therefore an Atlassian account so it can generate a trial licence key.
-