Jira Markup to Markdown Converter

0.5 · active · verified Fri Apr 17

jira2markdown is a Python library designed to convert text formatted with Jira markup into standard Markdown. It utilizes parsing expression grammars for robust conversion, handling various Jira elements like headings, lists, code blocks, and links. The current version is 0.5, and it maintains an active development cycle with minor releases addressing feature enhancements and bug fixes.

Common errors

```
ModuleNotFoundError: No module named 'jira2markdown'
```
cause The `jira2markdown` library has not been installed in your current Python environment.

fix Install the library using pip: `pip install jira2markdown`
```
TypeError: convert() missing 1 required positional argument: 'text'
```
cause The `convert` function was called without providing the required Jira formatted string as an argument.

fix Pass your Jira text as the first argument to the `convert` function, e.g., `markdown_output = convert("Your Jira text here")`.
```
SyntaxError: future feature annotations is not defined
```
cause You are attempting to run `jira2markdown` version 0.5 or newer on an unsupported Python version (e.g., Python 3.7 or 3.8).

fix Upgrade your Python environment to 3.9 or newer. Alternatively, if you cannot upgrade Python, install an older compatible version of the library: `pip install 'jira2markdown<0.5'`.

Warnings

breaking Version 0.5 and newer of `jira2markdown` require Python 3.9 or higher. Earlier versions supported Python 3.7+.
Fix: Upgrade your Python environment to 3.9 or newer, or pin `jira2markdown` to a version less than 0.5 (e.g., `pip install 'jira2markdown<0.5'`) if you must use an older Python version.
gotcha The `pyparsing` dependency has undergone specific version pinning and unpinning in the past (e.g., v0.3.5 pinned to 3.0.9, v0.3.6 unpinned). While the current requirement is `pyparsing>=3.0.0`, users might encounter parsing inconsistencies if they are using an outdated or incompatible `pyparsing` version manually.
Fix: Ensure `pyparsing` is installed according to `jira2markdown`'s requirements (`pyparsing>=3.0.0`). If issues arise, try recreating your virtual environment or explicitly installing `pyparsing` to the latest compatible version.
gotcha Table header delimiter changed in version 0.3.7 to `---` for compliance with YouTrack Markdown. This might affect how tables are rendered if you relied on a different delimiter in previous versions.
Fix: Review table rendering in your applications if you're upgrading from a version older than 0.3.7 and convert Jira markup containing tables.
gotcha Version 0.4 introduced changes to image rendering, specifically to handle images with properties using a YouTrack-like Markdown format.
Fix: Verify the output for images with attributes when upgrading from versions prior to 0.4, as their rendering might have changed.

Install

pip install jira2markdown Install latest version

Imports

convert
```
from jira2markdown import convert
```

Quickstart

Demonstrates converting a multi-line Jira formatted string containing headings, lists, code blocks, and a link into Markdown.

from jira2markdown import convert

jira_text = """
h1. Heading 1
* List item 1
** Sub-item 1
{code:python}
print("Hello, Jira!")
{code}
[https://example.com|Example Website]
"""

markdown_text = convert(jira_text)
print(markdown_text)

view raw JSON →