Skip to main content

Convert text from JIRA markup to Markdown using parsing expression grammars

Project description

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.

Table of Contents

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
{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)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

jira2markdown-0.3.tar.gz (11.2 kB view details)

Uploaded Source

Built Distribution

jira2markdown-0.3-py3-none-any.whl (12.9 kB view details)

Uploaded Python 3

File details

Details for the file jira2markdown-0.3.tar.gz.

File metadata

  • Download URL: jira2markdown-0.3.tar.gz
  • Upload date:
  • Size: 11.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.2.2 CPython/3.10.8 Linux/6.0.11-200.fc36.x86_64

File hashes

Hashes for jira2markdown-0.3.tar.gz
Algorithm Hash digest
SHA256 4563407e33e8097ef876e75cc76758b842eef4dad66c6f8371708ace9e99c233
MD5 a2cbc136fdb0128e635aed2b4b45e9f9
BLAKE2b-256 f517bff928e768a1876b6937732318369fdb28630130a175f1b7e1c093b0abe4

See more details on using hashes here.

File details

Details for the file jira2markdown-0.3-py3-none-any.whl.

File metadata

  • Download URL: jira2markdown-0.3-py3-none-any.whl
  • Upload date:
  • Size: 12.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.2.2 CPython/3.10.8 Linux/6.0.11-200.fc36.x86_64

File hashes

Hashes for jira2markdown-0.3-py3-none-any.whl
Algorithm Hash digest
SHA256 008f5de9fc0ab4a394dd9fd63a237b7359fac8d137afa13c4313e917ad3b6212
MD5 d59b00f3f35ba06be05d7158c33d9c4c
BLAKE2b-256 203ecd52fbe388f89e8847fff5e5e631c8990113552652b66594e648928cf562

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page