# asciidoctor-jira > [![Build status](https://github.com/uniqueck/asciidoctor-jira/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/uniqueck/asciidoctor-jira/actions/workflows/ci.yaml) [![npm version](http://img.shields.io/npm/v/asciidoctor-jira.svg)](http Latest version **5.1.0** (published 2026-05-22) · MIT license · 0 weekly downloads ## Install ```sh npm install asciidoctor-jira pnpm add asciidoctor-jira yarn add asciidoctor-jira bun add asciidoctor-jira ``` ## Health **Score 45/100 (D)** — status: active. Positive: no vulnerabilities. Warnings: low downloads; no types; no esm support. ## Facts | | | |---|---| | Version | 5.1.0 | | Published | 2026-05-22 | | First published | 2021-12-29 | | Weekly downloads | 0 | | License | MIT | | TypeScript types | none | | Module format | CommonJS | | Node | >=22 | | Dependencies | 9 | | Unpacked size | 72.1 KB | | Known vulnerabilities | 0 (+3 in 1 direct dependencies) | | Install scripts | no | | Author | Constantin Krüger | | Maintainers | uniqueck | | Keywords | asciidoctor, jira, antora | ## Links - npm: https://www.npmjs.com/package/asciidoctor-jira - Issues: https://github.com/doctoolchain/asciidoctor-jira/issues - npm.io page: https://npm.io/package/asciidoctor-jira ## Dependencies (9) - [rusha](https://npm.io/package/rusha.md) 0.8 - [unxhr](https://npm.io/package/unxhr.md) 1.2.0 - [dotenv](https://npm.io/package/dotenv.md) 17.4.2 - [lodash](https://npm.io/package/lodash.md) 4.17.21 - [mkdirp](https://npm.io/package/mkdirp.md) 3.0.1 - [then-request](https://npm.io/package/then-request.md) 6.0.2 - [http-proxy-agent](https://npm.io/package/http-proxy-agent.md) 7.0.2 - [plantuml-encoder](https://npm.io/package/plantuml-encoder.md) 1.4.0 - [https-proxy-agent](https://npm.io/package/https-proxy-agent.md) 7.0.6 ## Alternatives - [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads - [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads - [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads - [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads - [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads ## Recent versions - 5.1.0 (latest) — 2026-05-22 - 5.0.0 — 2026-05-12 - 4.1.2 — 2024-03-05 - 4.1.1 — 2024-02-05 - 4.1.0 — 2024-01-28 - 4.0.1 — 2024-01-03 - 4.0.0 — 2023-11-26 - 3.4.2 — 2023-11-24 - 3.4.1 — 2023-10-02 - 3.4.0 — 2023-10-01 - 3.3.1 — 2023-09-26 - 3.3.0 — 2023-09-26 - 3.2.0 — 2023-09-25 - 3.1.3 — 2023-09-22 - 3.1.2 — 2023-09-22 - … 14 more at https://npm.io/package/asciidoctor-jira/versions ## README # Asciidoctor Jira Extension [![Build status](https://github.com/uniqueck/asciidoctor-jira/actions/workflows/ci.yaml/badge.svg?branch=main)](https://github.com/uniqueck/asciidoctor-jira/actions/workflows/ci.yaml) [![npm version](http://img.shields.io/npm/v/asciidoctor-jira.svg)](https://www.npmjs.com/package/asciidoctor-jira) A set of macros for [Asciidoctor.js](https://github.com/asciidoctor/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: ```shell npm i asciidoctor asciidoctor-jira ``` Create a file named jira.js with following content and run it: ```javascript 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](https://antora.org/), you can integrate Jira in your documentation site. Install the extension in your playbook project: ```shell npm i asciidoctor-jira ``` Register the extension in your playbook file: ```yaml 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 ```adoc 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](https://uniqueck.github.io/asciidoctor-jira/antora-jira/blockmacro.html) ### inline macro ```adoc jira:DOC-123[] ``` ### roadmap macro ```adoc 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` | --- _Source: https://npm.io/package/asciidoctor-jira · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._