Convert JIRA to ADOC

Why Convert JIRA to ADOC?

Converting Jira markup to AsciiDoc allows you to migrate issue tracker content into professional technical documentation. Jira tickets often contain detailed technical descriptions, requirements, and decisions that are valuable beyond the issue tracker context.

AsciiDoc provides a structured, version-control friendly format that extends beyond Jira's platform-specific markup. Unlike Jira notation which only renders within Atlassian products, AsciiDoc files can be processed into HTML, PDF, EPUB, and DocBook, making your content publishable across any platform.

The conversion maps Jira syntax elements to their AsciiDoc equivalents: h1. headings become = level headings, *bold* stays *bold*, {code} blocks become delimited source blocks, and Jira tables are transformed into proper AsciiDoc table structures with |=== delimiters.

Key Benefits of Converting JIRA to ADOC:

• Documentation Quality: Transform issue content into polished technical documentation
• Version Control: Track changes with meaningful diffs in Git repositories
• Multi-Format Publishing: Generate HTML, PDF, and EPUB from a single AsciiDoc source
• Code Block Preservation: Jira {code} blocks become properly formatted AsciiDoc source blocks
• Platform Independence: Free your content from Atlassian platform lock-in
• Modular Includes: Use AsciiDoc include directives to compose larger documents from converted tickets
• Cross-References: Add navigation links, footnotes, and table of contents

Practical Examples

Example 1: Issue Description to AsciiDoc

Input JIRA file (issue.jira):

h1. Project Status Report

*Bold text* and _italic text_

||Column 1||Column 2||Column 3||
|Data A1|Data A2|Data A3|
|Data B1|Data B2|Data B3|

{code:java}
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello!");
    }
}
{code}

Output ADOC file (issue.adoc):

= Project Status Report

*Bold text* and _italic text_

[cols="3", options="header"]
|===
|Column 1 |Column 2 |Column 3

|Data A1 |Data A2 |Data A3
|Data B1 |Data B2 |Data B3
|===

[source,java]
----
public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello!");
    }
}
----

Example 2: Bug Report to AsciiDoc

Input JIRA file (bug.jira):

h2. Bug: Login Fails on Mobile

*Steps to reproduce:*
# Open mobile browser
# Navigate to login page
# Enter valid credentials
# Tap "Sign In" button

{panel:title=Expected Behavior}
User should be redirected to dashboard.
{panel}

{color:red}*Actual:* Login spinner hangs indefinitely.{color}

Output ADOC file (bug.adoc):

== Bug: Login Fails on Mobile

*Steps to reproduce:*

. Open mobile browser
. Navigate to login page
. Enter valid credentials
. Tap "Sign In" button

.Expected Behavior
****
User should be redirected to dashboard.
****

[red]*Actual:* Login spinner hangs indefinitely.

Example 3: Technical Specification to AsciiDoc

Input JIRA file (spec.jira):

h1. API Authentication Specification

h3. Overview
The API uses OAuth 2.0 for authentication with JWT tokens.

* Token expiry: 3600 seconds
** Refresh tokens valid for 30 days
* Supported grant types:
** authorization_code
** client_credentials

{noformat}
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...
Content-Type: application/json
{noformat}

[RFC 6749|https://tools.ietf.org/html/rfc6749]

Output ADOC file (spec.adoc):

= API Authentication Specification

=== Overview
The API uses OAuth 2.0 for authentication with JWT tokens.

* Token expiry: 3600 seconds
** Refresh tokens valid for 30 days
* Supported grant types:
** authorization_code
** client_credentials

....
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...
Content-Type: application/json
....

link:https://tools.ietf.org/html/rfc6749[RFC 6749]

Frequently Asked Questions (FAQ)

Q: How are Jira headings converted to AsciiDoc?

A: Jira headings h1. through h6. are mapped to AsciiDoc heading levels using = signs. For example, h1. becomes =, h2. becomes ==, and so on. This preserves the document hierarchy in the converted output.

Q: Are Jira code blocks preserved with syntax highlighting?

A: Yes. Jira {code:language} blocks are converted to AsciiDoc delimited source blocks with [source,language] attributes. For example, {code:java} becomes [source,java] followed by ---- delimiters, preserving syntax highlighting support.

Q: How are Jira tables converted to AsciiDoc tables?

A: Jira table headers (||header||) and data rows (|cell|) are transformed into AsciiDoc table syntax using |=== delimiters and pipe-separated values. The [cols] and [options="header"] attributes are added automatically.

Q: What happens to Jira macros like {panel} and {quote}?

A: Jira {panel} macros are converted to AsciiDoc sidebar blocks (****) with titles, and {quote} blocks become AsciiDoc quote blocks (____). The content within these macros is preserved in the appropriate AsciiDoc block structure.

Q: Are Jira links converted properly?

A: Yes. Jira link syntax [text|url] is converted to AsciiDoc link macro syntax link:url[text]. Both external URLs and anchor references are handled during the conversion process.

Q: Can I use the converted file with Asciidoctor directly?

A: Yes. The output is valid AsciiDoc that can be processed immediately by Asciidoctor to generate HTML, PDF, or other formats. You can also include the file in larger documentation projects using the include::[] directive.

Q: How is Jira {color} formatting handled?

A: Jira {color:red}text{color} markup is converted to AsciiDoc role-based styling where possible. AsciiDoc supports [red] and similar role annotations that can be styled via CSS when the document is rendered.

Q: What is the maximum file size supported?

A: Our converter handles Jira markup files of typical sizes used in issue tracking and documentation. Large files with extensive content are processed efficiently since both Jira markup and AsciiDoc are lightweight plain-text formats.