Skip to content

francescobonesi/asciidoctor-confluence

 
 

Repository files navigation

Asciidoctor-Confluence 0.0.3-SNAPSHOT

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

How to use it ?

Installation

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

Page management

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

Images management

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

Parameters for page update

Here is the list of arguments that can used with this gem

Table 1. Gem parameters for page
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

http://confluence.mydomain/

spaceKey

yes

The space wihtin the page will be created

'AS' in http://confluence.mydomain/display/AS/

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

Parameters for images update

Here is the list of arguments that can used with this gem

Table 2. Gem parameters for images
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

http://confluence.mydomain/

spaceKey

yes

The space wihtin the page will be created

'AS' in http://confluence.mydomain/display/AS/

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

Want to try it ?

If you want to try asciidoctor-confluence you can either download the gem:

gem install asciidoctor-confluence

Or install from the source

  1. Install the gem locally (at the moment it has not been publish to rubygem)

    1. Clone the github repository locally git clone https://github.com/francescobonesi/asciidoctor-confluence.git

    2. Built it gem build asciidoctor-confluence.gemspec

    3. Install it gem install ./asciidoctor-confluence.0.0.3-SNAPSHOT.gem

    4. To check it has been done correctly asciidoctor-confluence -v should display asciidoctor-confluence: 0.0.3-SNAPSHOT

  2. Have a Confluence instance

    1. 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.

About

No description, website, or topics provided.

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages

  • Ruby 100.0%