uniqueck / asciidoctor-jira

A set of macros to integrate Jira issues to your Asciidoc based documentation

Asciidoctor Jira Extension

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

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-baseurl / JIRA_BASEURL	Schema and domain of jira instance to use
jira-username / JIRA_USERNAME	Username to authenticate against given jira instance (Basic auth)
JIRA_APITOKEN	API token to authenticate against given jira instance (Basic auth)
JIRA_PASSWORD	Password to authenticate against given jira instance (Basic auth)
JIRA_PAT	Personal access token to authenticate against given jira instance (Bearer auth)

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