Package: jira2markdown
Overviewjira2markdownis a text converter fromJIRA markuptoYouTrack Markdownusing parsing expression grammars. The Markdown implementation in YouTrack follows theCommonMark specificationwith extensions. Thus,jira2markdowncan be used to convert text to any Markdown syntax with minimal modifications.Table of ContentsPrerequisitesInstallationUsageConversion tablesHeadingsText EffectsText BreaksLinksListsImagesTablesAdvanced FormattingCustomizationPrerequisitesPython 3.7+Installationpip install jira2markdownUsagefromjira2markdownimportconvertconvert("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 functionconvert("[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 lipsConversion tablesHeadingsJiraMarkdownh1. Biggest heading# Biggest headingh2. Bigger heading## Bigger headingh3. Big heading### Big headingh4. Normal heading#### Normal headingh5. Small heading##### Small headingh6. Smallest heading###### Smallest headingText EffectsJiraMarkdown*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 BreaksJiraMarkdown\\Line break---—--–LinksJiraMarkdown[#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]@usernameListsJiraMarkdown* some
* bullet
** indented
** bullets
* points- some
- bullet
  - indented
  - bullets
- points# a
# numbered
# list1. a
1. numbered
1. list# a
# numbered
#* with
#* nested
#* bullet
# list1. a
1. numbered
   - with
   - nested
   - bullet
1. list* a
* bulleted
*# with
*# nested
*# numbered
* list- a
- bulleted
  1. with
  1. nested
  1. numbered
- listImagesJiraMarkdown!image.jpg!
!image.jpg|thumbnail!
!image.gif|align=right, vspace=4!![image.jpg](image.jpg)!image.jpg|width=300, height=200!<img src="image.jpg" width="300" height="200" />TablesJiraMarkdown||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 FormattingJiraMarkdown{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>
```CustomizationTo customize the list of markup elements send it as an optional argument toconvert:fromjira2markdownimportconvertfromjira2markdown.elementsimportMarkupElementsfromjira2markdown.markup.linksimportLinkfromjira2markdown.markup.text_effectsimportBold# Only bold and link tokens will be converted hereelements=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 useinsert_after/replacemethods:fromjira2markdownimportconvertfromjira2markdown.elementsimportMarkupElementsfromjira2markdown.markup.baseimportAbstractMarkupfromjira2markdown.markup.linksimportLinkfromjira2markdown.markup.text_effectsimportColorclassCustomColor(Color):...classMyElement(AbstractMarkup):...elements=MarkupElements()elements.replace(Color,CustomColor)elements.insert_after(Link,MyElement)convert("Some Jira text here",elements=elements)