Overview

jira2markdown is a text converter from JIRA markup to YouTrack Markdown using parsing expression grammars. The Markdown implementation in YouTrack follows the CommonMark specification with extensions. Thus, jira2markdown can be used to convert text to any Markdown syntax with minimal modifications.

Prerequisites
Installation
Usage
Conversion tables
- Headings
- Text Effects
- Text Breaks
- Links
- Lists
- Images
- Tables
- Advanced Formatting
Customization

Prerequisites

Python 3.7+

Installation

pip install jira2markdown

Usage

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

Conversion tables

Headings

Jira	Markdown
`h1. Biggest heading`	`# Biggest heading`
`h2. Bigger heading`	`## Bigger heading`
`h3. Big heading`	`### Big heading`
`h4. Normal heading`	`#### Normal heading`
`h5. Small heading`	`##### Small heading`
`h6. Smallest heading`	`###### Smallest heading`

Text Effects

Jira	Markdown
`strong`	`strong`
`_emphasis_`	Not converted (the same syntax)
`??citation??`	`<q>citation</q>`
`-deleted-`	`~~deleted~~`
`+inserted+`	`inserted`
`^superscript^`	`<sup>superscript</sup>`
`~subscript~`	`<sub>subscript</sub>`
`{{monospaced}}`	`monospaced`
`bq. Some block quoted text`	`> Some block quoted text`
`{quote}Content to be quoted{quote}`	`> Content to be quoted`
`{color:red}red text!{color}`	`<font color="red">red text!</font>`

Text Breaks

Jira	Markdown
`\\`	Line break
`---`	`—`
`--`	`–`

Links

Jira	Markdown
`[#anchor]`	Not converted
`[^attachment.ext]`	`[attachment.ext](attachment.ext)`
`[http://www.example.com]`	`<http://www.example.com>`
`[Example\|http://example.com]`	`[Example](http://example.com)`
`[mailto:box@example.com]`	`<box@example.com>`
`[file:///c:/temp/foo.txt]`	Not converted
`{anchor:anchorname}`	Not converted
`[~username]`	`@username`

Lists

Jira	Markdown
`* some * bullet indented bullets * points`	`- some - bullet - indented - bullets - points`
`# a # numbered # list`	`1. a 1. numbered 1. list`
`# a # numbered #* with #* nested #* bullet # list`	`1. a 1. numbered - with - nested - bullet 1. list`
`* a * bulleted # with # nested # numbered list`	`- a - bulleted 1. with 1. nested 1. numbered - list`

Images

Jira	Markdown
`!image.jpg! !image.jpg\|thumbnail! !image.gif\|align=right, vspace=4!`	`![image.jpg](image.jpg)`

Tables

Jira	Markdown
`\|\|heading 1\|\|heading 2\|\|heading 3\|\| \|col A1\|col A2\|col A3\| \|col B1\|col B2\|col B3\|`	`\|heading 1\|heading 2\|heading 3\| \|-\|-\|-\| \|col A1\|col A2\|col A3\| \|col B1\|col B2\|col B3\|`

Advanced Formatting

Jira Markdown

Jira	Markdown
`{noformat} preformatted piece of text so no further _formatting_ is done here {noformat}`	``` preformatted piece of text so no further _formatting_ is done here ```
`{panel:title=My Title} Some text with a title {panel}`	`> My Title > Some text with a title`
`{code:xml} <test> <another tag="attribute"/> </test> {code}`	```xml <test> <another tag="attribute"/> </test> ```

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

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

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

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

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

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

Customization

To customize the list of markup elements send it as an optional argument to convert:

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)

Keep in mind that the order of markup elements is important! Elements are matching first from top to bottom in the list.

To override some elements in the default element list use insert_after/replace methods:

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)

Release files for jira2markdown 0.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jira2markdown 0.3
File	Size	Uploaded
jira2markdown-0.3.tar.gz	11.2 kB	Dec 6, 2022	Details

Built distribution (wheel)

Table of built distributions (wheels) for jira2markdown 0.3
File	Interpreter	ABI	Platform	Reset
jira2markdown-0.3-py3-none-any.whl 12.9 kB Dec 6, 2022	Python 3	none	any	Details

Total release size: 24.2 kB

Release files / jira2markdown-0.3.tar.gz

Download URL	jira2markdown-0.3.tar.gz
Size	11.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`4563407e33e8097ef876e75cc76758b842eef4dad66c6f8371708ace9e99c233`
BLAKE2b-256 checksum How to use checksums	`f517bff928e768a1876b6937732318369fdb28630130a175f1b7e1c093b0abe4`
Upload date	Dec 6, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.2.2 CPython/3.10.8 Linux/6.0.11-200.fc36.x86_64`

Release files / jira2markdown-0.3-py3-none-any.whl

Download URL	jira2markdown-0.3-py3-none-any.whl
Size	12.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`008f5de9fc0ab4a394dd9fd63a237b7359fac8d137afa13c4313e917ad3b6212`
BLAKE2b-256 checksum How to use checksums	`203ecd52fbe388f89e8847fff5e5e631c8990113552652b66594e648928cf562`
Upload date	Dec 6, 2022
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/1.2.2 CPython/3.10.8 Linux/6.0.11-200.fc36.x86_64`