https://github.com/uniqueck/asciidoctor-jira
A set of macros to integrate Jira issues to your Asciidoc based documentation
https://github.com/uniqueck/asciidoctor-jira
antora asciidoctor extension jira
Last synced: about 1 year ago
JSON representation
A set of macros to integrate Jira issues to your Asciidoc based documentation
- Host: GitHub
- URL: https://github.com/uniqueck/asciidoctor-jira
- Owner: uniqueck
- Created: 2021-11-16T00:40:53.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2025-03-17T05:02:33.000Z (about 1 year ago)
- Last Synced: 2025-03-21T18:51:56.273Z (about 1 year ago)
- Topics: antora, asciidoctor, extension, jira
- Language: JavaScript
- Homepage: https://uniqueck.github.io/asciidoctor-jira/antora-jira/index.html
- Size: 3.97 MB
- Stars: 4
- Watchers: 2
- Forks: 2
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Asciidoctor Jira Extension
[](https://github.com/uniqueck/asciidoctor-jira/actions/workflows/ci.yaml)
[](https://www.npmjs.com/package/asciidoctor-jira)
A set of macros for [Asciidoctor.js](https://github.com/asciidoctor/asciidoctor.js) to integrate Jira!
## 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-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
```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` |