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 |