### Install via pip

Source: https://github.com/catcombo/jira2markdown/blob/master/README.md

Standard installation using pip.

```bash
pip install jira2markdown
```

--------------------------------

### Install via pipx

Source: https://github.com/catcombo/jira2markdown/blob/master/README.md

Install the tool into an isolated environment using pipx.

```bash
pipx install jira2markdown
```

--------------------------------

### Convert tables

Source: https://github.com/catcombo/jira2markdown/blob/master/README.md

Example of converting JIRA table syntax to Markdown.

```text
||heading 1||heading 2||heading 3||
|col A1|col A2|col A3|
|col B1|col B2|col B3|
```

```text
|heading 1|heading 2|heading 3|
|---|---|---|
|col A1|col A2|col A3|
|col B1|col B2|col B3|
```

--------------------------------

### Convert basic images

Source: https://github.com/catcombo/jira2markdown/blob/master/README.md

Example of converting basic JIRA image syntax to Markdown.

```text
!image.jpg!
!image.jpg|thumbnail!
!image.gif|align=right, vspace=4!
```

```text
![image.jpg](image.jpg)
```

--------------------------------

### Convert numbered lists

Source: https://github.com/catcombo/jira2markdown/blob/master/README.md

Example of converting JIRA numbered lists to Markdown.

```text
# a
# numbered
# list
```

```text
1. a
1. numbered
1. list
```

--------------------------------

### Convert bulleted lists

Source: https://github.com/catcombo/jira2markdown/blob/master/README.md

Example of converting JIRA bulleted lists to Markdown.

```text
* some
* bullet
** indented
** bullets
* points
```

```text
- some
- bullet
  - indented
  - bullets
- points
```

--------------------------------

### Convert images with dimensions

Source: https://github.com/catcombo/jira2markdown/blob/master/README.md

Example of converting JIRA image syntax with width and height attributes to Markdown.

```text
!image.jpg|width=300, height=200!
```

```text
![image.jpg](image.jpg){width=300 height=200}
```

--------------------------------

### Convert nested numbered and bulleted lists

Source: https://github.com/catcombo/jira2markdown/blob/master/README.md

Example of converting nested JIRA lists to Markdown.

```text
# a
# numbered
#* with
#* nested
#* bullet
# list
```

```text
1. a
1. numbered
   - with
   - nested
   - bullet
1. list
```

--------------------------------

### Convert nested bulleted and numbered lists

Source: https://github.com/catcombo/jira2markdown/blob/master/README.md

Example of converting nested JIRA lists to Markdown.

```text
* a
* bulleted
*# with
*# nested
*# numbered
* list
```

```text
- a
- bulleted
  1. with
  1. nested
  1. numbered
- list
```

--------------------------------

### Convert Jira Links, MailTo, Attachments, and Mentions

Source: https://context7.com/catcombo/jira2markdown/llms.txt

Convert Jira URL formats, including aliased URLs, plain URLs, mailto links, attachments, and user mentions, into their corresponding Markdown or HTML representations. Handles URLs starting with 'www' by adding 'https://' and supports user mention mapping via account IDs.

```python
from jira2markdown import convert

# URL with alias: [alias|url] -> [alias](url)
result = convert("[Google|https://www.google.com]")
# Output: [Google](https://www.google.com)

# Plain URL: [url] -> <url>
result = convert("[https://www.example.com]")
# Output: <https://www.example.com>

# URLs starting with www get https:// prefix
result = convert("[www.example.com]")
# Output: <https://www.example.com>

# Email: [mailto:email] -> <email>
result = convert("[mailto:support@example.com]")
# Output: <support@example.com>

# Email with alias
result = convert("[Contact Support|mailto:support@example.com]")
# Output: [Contact Support](mailto:support@example.com)

# Attachment: [^filename] -> [filename](filename)
result = convert("See the attached file [^report.pdf]")
# Output: See the attached file [report.pdf](report.pdf)

# User mention: [~username] -> @username
result = convert("[~johndoe] please review this")
# Output: @johndoe please review this

# User mention with account ID mapping
usernames = {"abc-123": "johndoe", "xyz-456": "janedoe"}
result = convert(
    "[~accountid:abc-123] assigned to [~accountid:xyz-456]",
    usernames
)
# Output: @johndoe assigned to @janedoe
```

--------------------------------

### Replace Jira Markup Element with Custom Implementation

Source: https://context7.com/catcombo/jira2markdown/llms.txt

Use the `replace()` method to substitute default markup element conversions with custom logic. This example replaces the default color conversion to use CSS classes instead of font tags.

```python
from jira2markdown import convert
from jira2markdown.elements import MarkupElements
from jira2markdown.markup.text_effects import Color
from pyparsing import ParseResults

class CustomColor(Color):
    """Convert JIRA colors to HTML spans with CSS classes instead of font tags."""

    def action(self, tokens: ParseResults) -> str:
        text = self.inline_markup.transform_string(tokens.text)
        color = tokens.color[0]
        # Use CSS class instead of inline color
      
        return f'<span class="text-{color}">{text}</span>'

elements = MarkupElements()
elements.replace(Color, CustomColor)
result = convert("{color:red}Warning message{color}", elements=elements)
# Output: <span class="text-red">Warning message</span>
```

--------------------------------

### Use the jira2markdown CLI

Source: https://context7.com/catcombo/jira2markdown/llms.txt

The command-line interface supports direct text input, file processing, and piping for automated workflows.

```bash
# Install with pipx for isolated environment
pipx install jira2markdown

# Convert text directly as an argument
jira2markdown "*bold text* and [link|https://example.com]"
# Output: **bold text** and [link](https://example.com)

# Convert from a file
jira2markdown -f /path/to/jira-content.txt

# Pipe input from another command
echo "{quote}Important quote{quote}" | jira2markdown
# Output: > Important quote

# Convert a JIRA issue description
cat jira-issue.txt | jira2markdown > markdown-issue.md
```

--------------------------------

### Customizing Markup Elements

Source: https://github.com/catcombo/jira2markdown/blob/master/README.md

Demonstrates how to restrict conversion to specific elements by passing a custom MarkupElements list to the convert function.

```python
from jira2markdown import convert
from jira2markdown.elements import MarkupElements
from jira2markdown.markup.links import Link
from jira2markdown.markup.text_effects import Bold

# Only bold and link tokens will be converted here
elements = MarkupElements([Link, Bold])
convert("Some Jira text here", elements=elements)
```

--------------------------------

### Configure custom MarkupElements

Source: https://context7.com/catcombo/jira2markdown/llms.txt

The MarkupElements class allows defining specific converters and their processing order. Elements are matched sequentially.

```python
from jira2markdown import convert
from jira2markdown.elements import MarkupElements
from jira2markdown.markup.links import Link, Attachment, Mention
from jira2markdown.markup.text_effects import Bold, Strikethrough, Color

# Create a custom element list with only specific converters
elements = MarkupElements([Link, Bold, Strikethrough])
result = convert(
    "*Bold* and [link|https://example.com] with -strikethrough-",
    elements=elements
)
# Output: **Bold** and [link](https://example.com) with ~~strikethrough~~

# Note: Color won't be converted since it's not in our custom list
result = convert("{color:red}Red text{color}", elements=elements)
# Output: {color:red}Red text{color} (unchanged)
```

--------------------------------

### Convert JIRA Images

Source: https://context7.com/catcombo/jira2markdown/llms.txt

Converts JIRA image syntax to Markdown, handling dimensions and stripping unsupported attributes.

```python
from jira2markdown import convert

# Basic image
result = convert("!screenshot.png!")

# Image with dimensions
result = convert("!diagram.jpg|width=500, height=300!")

# Image with thumbnail (attributes stripped)
result = convert("!photo.gif|thumbnail!")

# Multiple images in text
result = convert("Before !image1.png! middle !image2.png! after")
```

--------------------------------

### Convert JIRA Quotes and Panels

Source: https://context7.com/catcombo/jira2markdown/llms.txt

Converts JIRA quote and panel syntax into Markdown blockquotes.

```python
from jira2markdown import convert

# Inline quote: bq. text -> > text
result = convert("bq. This is a quoted line")

# Block quote: {quote}text{quote} -> > text
jira_blockquote = """{quote}
This is a longer quote
that spans multiple lines
with *formatting* support
{quote}"""

result = convert(jira_blockquote)

# Panel with title
jira_panel = """{panel:title=Important Notice|borderStyle=solid}
Please read this carefully.
This contains *critical* information.
{panel}"""

result = convert(jira_panel)

# Panel without title
result = convert("{panel}Simple panel content{panel}")
```

--------------------------------

### Jira Panel to Markdown Blockquote

Source: https://github.com/catcombo/jira2markdown/blob/master/README.md

Maps Jira {panel} elements to Markdown blockquotes with bold titles.

```text
{panel:title=My Title}
Some text with a title
{panel}
```

```markdown
> **My Title**
> Some text with a title
```

--------------------------------

### convert() Function

Source: https://context7.com/catcombo/jira2markdown/llms.txt

The primary function for converting JIRA markup strings into Markdown format.

```APIDOC
## convert(text, usernames=None, elements=None)

### Description
Converts a string containing JIRA markup into Markdown syntax.

### Parameters
- **text** (str) - Required - The JIRA markup string to convert.
- **usernames** (dict) - Optional - A mapping dictionary for resolving JIRA account IDs to usernames.
- **elements** (MarkupElements) - Optional - A custom configuration of markup elements to use for conversion.

### Response
- **result** (str) - The converted Markdown string.
```

--------------------------------

### MarkupElements Class

Source: https://context7.com/catcombo/jira2markdown/llms.txt

Configuration class for managing and extending the markup elements used during conversion.

```APIDOC
## MarkupElements(elements_list)

### Description
Manages the list of markup elements and their processing order. Elements are processed in the order they appear in the list.

### Methods
- **insert_after(existing_element, new_element)** - Inserts a new markup element after an existing one in the processing chain.
```

--------------------------------

### Convert JIRA Tables to Markdown

Source: https://context7.com/catcombo/jira2markdown/llms.txt

Converts JIRA table syntax, including cell formatting like bold and color, into Markdown tables.

```python
jira_formatted_table = """||Feature||Status||
|*Bold feature*|{color:green}Active{color}|
|_Italic feature_|_{color:red}Inactive{color}|"""

result = convert(jira_formatted_table)
```

--------------------------------

### Extend conversion with insert_after

Source: https://context7.com/catcombo/jira2markdown/llms.txt

The insert_after method allows injecting custom converters into the existing processing chain at a specific position.

```python
from jira2markdown import convert
from jira2markdown.elements import MarkupElements
from jira2markdown.markup.base import AbstractMarkup
from jira2markdown.markup.links import Link
from pyparsing import Regex

class CustomEmoji(AbstractMarkup):
    """Convert JIRA emoticons to emoji."""

    @property
    def expr(self):
        patterns = {
            r'\(\+\)': '👍',
            r'\(-\)': '👎',
            r'\(\?\)': '❓',
            r'\(!!\)': '⚠️',
        }
        return Regex(r'\(\+\)|\(-\)|\(\?\)|\(!!\)').set_parse_action(
            lambda t: patterns.get(t[0], t[0])
        )

elements = MarkupElements()
elements.insert_after(Link, CustomEmoji)
result = convert("Great job (+) but needs review (?)")
# Output: Great job 👍 but needs review ❓
```

--------------------------------

### Convert JIRA markup using Python API

Source: https://github.com/catcombo/jira2markdown/blob/master/README.md

Use the convert function to transform JIRA markup strings. User mentions can be resolved by providing a mapping dictionary.

```python
from jira2markdown import convert

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

# To convert user mentions provide a mapping Jira internal account id to username 
# as a second argument to convert function
convert("[Winston Smith|~accountid:internal-id] woke up with the word 'Shakespeare' on his lips", {
    "internal-id": "winston",
})
# >>> @winston woke up with the word 'Shakespeare' on his lips
```

--------------------------------

### Jira Noformat to Markdown Code Block

Source: https://github.com/catcombo/jira2markdown/blob/master/README.md

Maps Jira {noformat} blocks to standard Markdown code blocks.

```text
{noformat}
preformatted piece of text
 so *no* further _formatting_ is done here
{noformat}
```

```markdown
```
preformatted piece of text
 so *no* further _formatting_ is done here
```
```

--------------------------------

### Convert JIRA Code and Noformat Blocks

Source: https://context7.com/catcombo/jira2markdown/llms.txt

Transforms JIRA code and noformat blocks into Markdown fenced code blocks, supporting language specification.

```python
from jira2markdown import convert

# Code block with language
jira_code = """{code:python}
def fibonacci(n):
    if n <= 1:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

print(fibonacci(10))
{code}"""

result = convert(jira_code)

# Code block without language defaults to Java
jira_default = """{code}
public class Hello {
    public static void main(String[] args) {
        System.out.println("Hello");
    }
}
{code}"""

result = convert(jira_default)

# Noformat block (preformatted text)
jira_noformat = """{noformat}
preformatted piece of text
 so *no* further _formatting_ is done here
{noformat}"""

result = convert(jira_noformat)
```

--------------------------------

### Convert Jira Tables to Markdown

Source: https://context7.com/catcombo/jira2markdown/llms.txt

Convert Jira tables, defined with `||` for headers and `|` for rows, into standard Markdown table format, including the header separator line.

```python
from jira2markdown import convert

# Basic table with headers (||) and rows (|)
jira_table = """
||Name||Age||City||
|Alice|30|New York|
|Bob|25|San Francisco|
|Charlie|35|Chicago|"""

result = convert(jira_table)
# Output:
# |Name|Age|City|
# |---|---|---|
```

--------------------------------

### Convert Jira Text Effects to Markdown/HTML

Source: https://context7.com/catcombo/jira2markdown/llms.txt

Convert common Jira text formatting like bold, strikethrough, underline, citation, superscript, subscript, monospaced, and color to their Markdown or HTML representations. Supports nested formatting.

```python
from jira2markdown import convert

# Bold: *text* -> **text**
result = convert("This is *bold text* in JIRA")
# Output: This is **bold text** in JIRA

# Strikethrough: -text- -> ~~text~~
result = convert("This is -deleted text- in JIRA")
# Output: This is ~~deleted text~~ in JIRA

# Underline: +text+ -> <u>text</u>
result = convert("This is +underlined text+ in JIRA")
# Output: This is <u>underlined text</u> in JIRA

# Citation: ??text?? -> <q>text</q>
result = convert("As the saying goes: ??to be or not to be??")
# Output: As the saying goes: <q>to be or not to be</q>

# Superscript: ^text^ -> <sup>text</sup>
result = convert("E = mc^2^")
# Output: E = mc<sup>2</sup>

# Subscript: ~text~ -> <sub>text</sub>
result = convert("H~2~O is water")
# Output: H<sub>2</sub>O is water

# Monospaced: {{text}} -> `text`
result = convert("Use the {{print()}} function")
# Output: Use the `print()` function

# Color: {color:name}text{color} -> <font color="name">text</font>
result = convert("{color:red}Error: file not found{color}")
# Output: <font color="red">Error: file not found</font>

# Nested formatting
result = convert("*Bold with {color:blue}colored text{color} inside*")
# Output: **Bold with <font color="blue">colored text</font> inside**
```

--------------------------------

### Jira Code Block to Markdown XML

Source: https://github.com/catcombo/jira2markdown/blob/master/README.md

Maps Jira {code} blocks to language-specific Markdown code blocks.

```text
{code:xml}
    <test>
        <another tag="attribute"/>
    </test>
{code}
```

```markdown
```xml
    <test>
        <another tag="attribute"/>
    </test>
```
```

--------------------------------

### Overriding Default Markup Elements

Source: https://github.com/catcombo/jira2markdown/blob/master/README.md

Shows how to modify the default element list using replace and insert_after methods for custom element behavior.

```python
from jira2markdown import convert
from jira2markdown.elements import MarkupElements
from jira2markdown.markup.base import AbstractMarkup
from jira2markdown.markup.links import Link
from jira2markdown.markup.text_effects import Color

class CustomColor(Color):
    ...

class MyElement(AbstractMarkup):
    ...

elements = MarkupElements()
elements.replace(Color, CustomColor)
elements.insert_after(Link, MyElement)
convert("Some Jira text here", elements=elements)
```

--------------------------------

### Convert JIRA Text Breaks and Special Characters

Source: https://context7.com/catcombo/jira2markdown/llms.txt

Handles conversion of line breaks, horizontal rules, and dashes.

```python
from jira2markdown import convert

# Line break: \\ -> newline
result = convert("First line\\Second line")

# Horizontal ruler: ---- at line start
result = convert("Above\n----\nBelow")

# En-dash: -- -> –
result = convert("Pages 10--20")

# Em-dash: --- -> —
result = convert("Wait---there's more")
```

--------------------------------

### Convert Jira Lists to Markdown

Source: https://context7.com/catcombo/jira2markdown/llms.txt

Convert Jira unordered and ordered lists to Markdown format, preserving indentation for nested lists. Supports mixing numbered and bulleted list types.

```python
from jira2markdown import convert

# Unordered list: * -> -
jira_list = """
* First item
* Second item
** Nested item
** Another nested
*** Deep nested
* Third item"""

result = convert(jira_list)
# Output:
# - First item
# - Second item
#   - Nested item
#   - Another nested
#     - Deep nested
# - Third item

# Ordered list: # -> 1.
jira_numbered = """
# Step one
# Step two
## Sub-step A
## Sub-step B
# Step three"""

result = convert(jira_numbered)
# Output:
# 1. Step one
# 1. Step two
#    1. Sub-step A
#    1. Sub-step B
# 1. Step three

# Mixed lists: numbered with nested bullets
jira_mixed = """
# Main item
#* Bullet under numbered
#* Another bullet
# Second main item"""

result = convert(jira_mixed)
# Output:
# 1. Main item
#    - Bullet under numbered
#    - Another bullet
# 1. Second main item
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.