---
id: jira2markdown
version: "0.5.1"
license: MIT
license_treatment: permissive
maintenance: active
---

# jira2markdown — Convert text from JIRA markup to Markdown using parsing expression grammars

License: permissive · Maintenance: active · Downloads: 89.8K/mo

## What it is and what it does

jira2markdown is a text converter that takes JIRA markup syntax and transforms it into Markdown compatible with the CommonMark specification. It uses parsing expression grammars to handle a wide range of JIRA formatting constructs—headings, bold/italic text, links, lists, tables, code blocks, and special elements like quotes and panels—converting them to their Markdown equivalents. The library can be used as a Python module for programmatic conversion or as a command-line tool via pipx.

The package is useful for migrating documentation from JIRA to Markdown-based systems (like YouTrack, GitHub, or static site generators) or for converting JIRA text to any Markdown dialect with minimal post-processing. It supports customization through a pluggable element system, allowing you to override or extend the default conversion rules. A single optional argument lets you map JIRA user mentions to usernames for proper @-mention conversion.

Use it for:

- Migrate JIRA documentation and issue descriptions to Markdown-based platforms like YouTrack or GitHub.
- Batch convert JIRA markup in exported data or backups to standard Markdown for archival or republishing.
- Build a documentation pipeline that accepts JIRA input and outputs Markdown for static site generators.
- Customize conversion rules for domain-specific JIRA markup extensions or non-standard formatting.
- Convert JIRA text snippets in CLI scripts or automation workflows using the command-line interface.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Converts JIRA markup text to Markdown (CommonMark-compatible) using parsing expression grammars, with support for headings, text effects, links, lists, tables, and code blocks.

Yes, if you need to convert JIRA markup to Markdown. The package has low install friction, active maintenance, permissive licensing, and no known vulnerabilities. The Alpha status reflects early development but does not indicate instability—the conversion tables are well-documented and the API is straightforward. Suitable for production use in migration and batch-processing tasks.

## Install

pip install jira2markdown
uv add jira2markdown
poetry add jira2markdown

## Installing jira2markdown

Before you install: Low friction install with a single runtime dependency (pyparsing). Active maintenance as of 2026-08-13, though classified as Alpha. No known vulnerabilities.

License in practice: MIT license (permissive) allows use, modification, and distribution with minimal restrictions, making it suitable for both open-source and commercial projects.

Quickstart:

pip install jira2markdown

from jira2markdown import convert

result = convert("Some *Jira text* formatting [example|https://example.com].")
print(result)  # Some **Jira text** formatting [example](https://example.com).

Requires Python 3.9 or later.

Verify before relying:

- Whether the conversion handles all JIRA markup edge cases or only the documented subset.
- Performance characteristics when converting large documents or batch processing.
- Stability guarantees given the Alpha development status classification.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 89.8K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

jira to markdown converter, jira markup text conversion, jira wiki to markdown, convert jira formatting, jira parser markdown, markup language converter, jira documentation migration, format-conversion, jira-migration, cli-tool

[View on SkillFed](https://skillfed.io/packages/jira2markdown) · [View on PyPI](https://pypi.org/project/jira2markdown/)