Asciidoctorj extension to create links to an issue in JIRA.

URLs

Do you want to improve this page? Please edit it on GitHub.

Description

This extension creates links to issues on a jira server, based on its identifier.

Target

The target is the jira identifier itself (JENKINS-57098 for the Jenkins Jira for example). This is mandatory.

Parameters

The macro supports following parameters that can be used as named parameters (no matter the order) or as ordered parameters:

  1. text: link text.

  2. type: type of link, see Specifying the type for details.

  3. server: jira server, see Specifying the server for details.

Specifying the server

The jira server needs to be specified. This is possible with the server parameter in the macro. An other possibility is to use jira-server in the document in order to do this only once.

If you are mixing different jira issues coming from different jira servers, you can define different document attributes: jira-server-<prefix> where <prefix> is the prefix of the issue identifier (if you are referring to an issue identified as TASK-1234 you can define the server with jira-server-task).

Specifying the type

To specify the type that need to be created, the type parameter can be used, or globally jira-type can be defined in the document.

Possible values:

  • link: a link is created (this is the default)

  • link-new-window: same as link, but the link are opened in a new window.

  • text: only a text is created (this is the fallback when the server is not defined). This can also be used if the jira server is not available publicly.

Examples

Listing 1 demonstrates a simple usage of the macro. Server and type are specified on the document (so that they are shared for all macro usage). In this example, the jira: macro is used without any additional arguments.

Listing 1. Simple usage
:jira-server: https://issues.jenkins-ci.org/
:jira-type: link-new-window

I have created issue jira:JENKINS-57098[] to discuss it.
Example 1. Output (simple usage)

I have created issue JENKINS-57098 to discuss it.

Listing 2 shows that different jira server urls can be used. First option is to define it as parameter of the macro, but in this case you need to do it each time you call the jira: macro. Second option is to define it at document level. Either with jira-server (default for all issues) or with jira-server-jenkins which will be used for all JENKINS-xxx issues.

Listing 2. Define specific servers for the different issues
:jira-server-JENKINS: https://issues.jenkins-ci.org
:jira-server: https://jira.sonarsource.com/
:jira-type: link-new-window

At the time of writing the newest issues were:
jira:MNG-6581[server="https://issues.apache.org/jira/"], jira:JENKINS-57550[], jira:SONARJAVA-3105[] and jira:SONARPHP-880[]
Example 2. Output (specific servers)

At the time of writing the newest issues were: MNG-6581, JENKINS-57550, SONARJAVA-3105 and SONARPHP-880

Listing 3 is an example of the macro usage with only inlined parameters. It is using ordered parameters, but you can also used named parameters if you prefer.

Listing 3. Inline parameters
I have raised issue jira:JENKINS-57098[this issue, LINK_NEW_WINDOW, https://issues.jenkins-ci.org/] to discuss it.
Example 3. Output (inline parameters)

I have raised issue this issue to discuss it.

Usage

The extension is published on maven central and can be directly consumed from maven or gradle.

Integration in a maven build

You need to declare fr.jmini.asciidoctorj:jira as a dependency for the org.asciidoctor:asciidoctor-maven-plugin plugin. Your <build> section could look like this:

<build>
  <plugins>
    <plugin>
      <groupId>org.asciidoctor</groupId>
      <artifactId>asciidoctor-maven-plugin</artifactId>
      <version>${asciidoctor.maven.plugin.version}</version>
      <dependencies>
        <dependency> (1)
          <version>1.1.0</version>
          <groupId>fr.jmini.asciidoctorj</groupId>
          <artifactId>jira</artifactId>
        </dependency>
        <!-- ... (other dependencies) -->
      </dependencies>
      <!-- ... (configuration and executions sections) -->
    </plugin>
    <!-- ... (other plugins) -->
  </plugins>
</build>
1 Dependency declaration

For a complete example, see: pom.xml

Integration in a gradle build

The fr.jmini.asciidoctorj:jira jar can be declared as dependency of the asciidoctor task:

asciidoctor {
    sourceDir = file('docs')
    sources {
        include 'index.adoc'
    }
    outputDir = file('build/generated-docs')
    attributes = ['project-version'      : "$version",
                  'jira-server'          : 'https://jira.sonarsource.com/', (2)
                  'toc'                  : 'left',
                  'icons'                : 'font',
                  'sectanchors'          : 'true',
                  'idprefix'             : '',
                  'idseparator'          : '-']
    repositories {
        mavenCentral()
    }
    dependencies {
        asciidoctor 'fr.jmini.asciidoctorj:jira:1.1.0' (1)
    }
}
1 Dependency declaration
2 Example configuration

For a complete example, see: build.gradle

AsciidoctorJ version

The latest version of this extension is built and tested with version 2.0.0 of org.asciidoctor:asciidoctorj. If you are using an older version of AsciidoctorJ, you can use an older version of this plugin:

Asciidoctorj version

jira:[] version

1.6.x

1.0.1

2.0.x

1.1.0

Source Code

As for any grade plugin, the source code of the plugin is available in the src/ folder.

Build

This project is using gradle.

Command to build the sources locally:

./gradlew build

Command to deploy to your local maven repository:

./gradlew publishToMavenLocal

Command to build the documentation page:

./gradlew asciidoctor

The output of this command is an HTML page located at <git repo root>/build/docs/html5/index.html.

For project maintainers

signing.gnupg.keyName and signing.gnupg.passphrase are expected to be set in your local gradle.properties file to be able to sign. sonatypeUser and sonatypePassword are expected to be set in order to be able to publish to a distant repository.

Command to build and publish the result to maven central:

./gradlew publishToNexus

Command to upload the documentation page on GitHub pages:

./gradlew gitPublishPush

Command to perform a release:

./gradlew release -Prelease.useAutomaticVersion=true

Using ssh-agent

Some tasks requires pushing into the distant git repository (release task or updating the gh-pages branch). If they are failing with errors like this:

org.eclipse.jgit.api.errors.TransportException: ... Permission denied (publickey).

Then ssh-agent can be used.

eval `ssh-agent -s`
ssh-add ~/.ssh/id_rsa

(source for this approach)

Get in touch

Use the jira:[] issue tracker on GitHub.

You can also contact me on Twitter: @j2r2b

License

Eclipse Public License - v 2.0