Asciidoctor Jira Extension

A set of macros for Asciidoctor.js to integrate Jira Cloud!

Note: The current release supports Jira Cloud with REST API Version 3 only.

Install

Node.js

Install the dependencies:

npm i asciidoctor asciidoctor-jira

Create a file named jira.js with following content and run it:

const asciidoctor = require('@asciidoctor/core')()
const jira = require('asciidoctor-jira')

const input = 'jira::DOC[]'

jira.register(asciidoctor.Extensions) // <1>
console.log(asciidoctor.convert(input, { safe: 'safe' }))

const registry = asciidoctor.Extensions.create()
jira.register(registry) // <2>
console.log(asciidoctor.convert(input, { safe: 'safe', extension_registry: registry }))

<1> Register the extension in the global registry

<2> Register the extension in a dedicated registry

Antora Integration

If you are using Antora, you can integrate Jira in your documentation site.

Install the extension in your playbook project:

npm i asciidoctor-jira

Register the extension in your playbook file:

asciidoc:
  extensions:
    - asciidoctor-jira

Usage

common

For this extension in general you have to provide the following minimal attributes and/or environment variables.

Attribute / Env variable	Description
JIRA_API_TOKEN	API token used as Bearer token for Jira REST API authentication
JIRA_CLIENT_ID	OAuth 2.0 client ID used to request an access token
JIRA_CLIENT_SECRET	OAuth 2.0 client secret used together with the client ID to request a token
JIRA_CLOUD_NAME	Jira Cloud site name (for example mycompany) used to resolve the Cloud ID
JIRA_HTTP_PROXY	Optional proxy URL used for HTTP Jira requests and as HTTPS fallback
JIRA_HTTPS_PROXY	Optional proxy URL used for HTTPS Jira requests
JIRA_NO_PROXY	Optional comma-separated host list that bypasses the configured proxy

Proxy lookup is Jira-specific: HTTPS requests use JIRA_HTTPS_PROXY, then fall back to JIRA_HTTP_PROXY; HTTP requests use JIRA_HTTP_PROXY. JIRA_NO_PROXY bypasses both when the host matches.

block macro

jira::DOC[]

To control the header of the generated table, you can define Asciidoctor attribute e.g. :jira-table-header-status-label: Status. If no asciidoctor attribute for a given field is provided, the field name is used as table header. To control the default value for an empty field value, you can define an Asciidoctor attribute e.g. :jira-table-status-default: No Status, if no attribute is present, the sign - is used in general. For more examples and configuration settings see documentation

inline macro

jira:DOC-123[]

roadmap macro

roadmap::DOC[]

Configuration

Macro type	Attribute name	Description	Default value
block	jql	Define the query to obtain issues from jira instance.	resolution='Unresolved' ORDER BY priority DESC, key ASC, duedate ASC
block	customFieldIds	Create only for these custom fields a table	priority,created,assignee,issuetype,summary