Convert JIRA to AsciiDoc

Why Convert JIRA to AsciiDoc?

Converting Jira markup to AsciiDoc enables you to transition issue tracker documentation into a professional publishing format suitable for technical books, software manuals, and standards documents. AsciiDoc extends far beyond Jira's formatting capabilities.

While Jira markup is powerful within the Atlassian ecosystem, it cannot produce standalone documents or be processed outside of Atlassian tools. AsciiDoc breaks this limitation by providing a portable, tool-independent markup that renders identically across platforms.

AsciiDoc's advanced features like document attributes, conditional content, modular includes, and cross-references make it ideal for building comprehensive documentation from content originally written in Jira tickets and Confluence pages.

Key Benefits of Converting JIRA to AsciiDoc:

• Professional Publishing: Create book-quality documents from Jira content
• Multi-Format Output: Generate HTML, PDF, EPUB, and DocBook from one source
• Modular Documentation: Combine converted tickets into larger document structures
• Version Control: Store and track documentation changes in Git
• Platform Independence: Free content from Atlassian platform dependency
• Advanced Features: Add cross-references, TOC, indexes, and conditional content
• Syntax Highlighting: Preserve code blocks with full language highlighting
• Archival Quality: Create long-term documentation from ephemeral ticket content

Practical Examples

Example 1: Feature Specification to AsciiDoc

Input JIRA file (feature.jira):

h1. User Authentication Module

h2. Requirements
* Users must authenticate via OAuth 2.0
* Session timeout: 30 minutes
** Configurable per organization
* Support MFA (multi-factor authentication)

{code:python}
def authenticate(username, password):
    user = User.objects.get(username=username)
    if user.check_password(password):
        return generate_token(user)
    raise AuthenticationError("Invalid credentials")
{code}

||Feature||Priority||Status||
|OAuth 2.0|High|Complete|
|MFA Support|Medium|In Progress|
|SSO|Low|Planned|

Output AsciiDoc file (feature.asciidoc):

= User Authentication Module

== Requirements
* Users must authenticate via OAuth 2.0
* Session timeout: 30 minutes
** Configurable per organization
* Support MFA (multi-factor authentication)

[source,python]
----
def authenticate(username, password):
    user = User.objects.get(username=username)
    if user.check_password(password):
        return generate_token(user)
    raise AuthenticationError("Invalid credentials")
----

[cols="3", options="header"]
|===
|Feature |Priority |Status

|OAuth 2.0 |High |Complete
|MFA Support |Medium |In Progress
|SSO |Low |Planned
|===

Example 2: Release Notes to AsciiDoc

Input JIRA file (release.jira):

h1. Release Notes v3.2.0

h3. New Features
# Dashboard redesign with real-time charts
# Export reports to PDF and Excel
# Dark mode support

h3. Bug Fixes
* {color:red}Fixed:{color} Login timeout on slow connections
* {color:red}Fixed:{color} CSV export encoding issues

{quote}
This release focuses on improving the user experience
and addressing critical stability issues reported by
enterprise customers.
{quote}

Output AsciiDoc file (release.asciidoc):

= Release Notes v3.2.0

=== New Features
. Dashboard redesign with real-time charts
. Export reports to PDF and Excel
. Dark mode support

=== Bug Fixes
* [red]*Fixed:* Login timeout on slow connections
* [red]*Fixed:* CSV export encoding issues

[quote]
____
This release focuses on improving the user experience
and addressing critical stability issues reported by
enterprise customers.
____

Example 3: Architecture Decision to AsciiDoc

Input JIRA file (adr.jira):

h1. ADR-005: Adopt Microservices Architecture

h2. Context
The monolithic application has reached scaling limits.

h2. Decision
We will decompose the system into microservices.

{panel:title=Key Services}
* *auth-service* - Authentication and authorization
* *order-service* - Order processing pipeline
* *notification-service* - Email and push notifications
{panel}

{noformat}
Service communication: gRPC for internal, REST for external
Message broker: Apache Kafka
Service mesh: Istio
{noformat}

Output AsciiDoc file (adr.asciidoc):

= ADR-005: Adopt Microservices Architecture

== Context
The monolithic application has reached scaling limits.

== Decision
We will decompose the system into microservices.

.Key Services
****
* *auth-service* - Authentication and authorization
* *order-service* - Order processing pipeline
* *notification-service* - Email and push notifications
****

....
Service communication: gRPC for internal, REST for external
Message broker: Apache Kafka
Service mesh: Istio
....

Frequently Asked Questions (FAQ)

Q: What is the difference between ADOC and AsciiDoc formats?

A: ADOC and AsciiDoc refer to the same markup language. The difference is in the file extension: .adoc is the modern preferred extension, while .asciidoc is the longer traditional form. Both produce identical output when processed by Asciidoctor.

Q: How are Jira macros converted to AsciiDoc?

A: Jira macros are mapped to equivalent AsciiDoc blocks. {code} becomes delimited source blocks, {panel} becomes sidebar blocks (****), {quote} becomes quote blocks (____), and {noformat} becomes literal blocks (....).

Q: Can I process the converted file with Asciidoctor?

A: Yes. The output is valid AsciiDoc that Asciidoctor can process immediately. Run asciidoctor file.asciidoc to generate HTML, or use asciidoctor-pdf for PDF output.

Q: How are nested Jira lists handled?

A: Jira nested lists using ** (sub-bullets) and ## (sub-numbered) are converted to AsciiDoc nested list syntax with proper indentation and markers. The hierarchy and nesting depth are preserved.

Q: Does the conversion preserve Jira table formatting?

A: Yes. Jira tables with ||header|| and |cell| syntax are converted to AsciiDoc table blocks with proper column definitions, header rows, and cell content. Column alignment can be adjusted in the converted output.

Q: Are Jira emoticons and special characters handled?

A: Jira emoticons like :) and :( are converted to their Unicode equivalents or plain text representations. Special characters and Unicode content are preserved in the UTF-8 AsciiDoc output.

Q: Can I batch convert multiple Jira files?

A: You can upload and convert multiple Jira files in a single session. Each file is processed independently and produces a corresponding AsciiDoc output file that you can download.

Q: How does this compare to manual Jira-to-AsciiDoc conversion?

A: Manual conversion of Jira markup to AsciiDoc is tedious and error-prone, especially with complex tables and nested lists. Our automated converter handles all syntax mappings consistently and correctly, saving significant time on documentation migration projects.