# Overview
`jira2markdown` is a text converter from [JIRA markup](https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all) to [YouTrack Markdown](https://www.jetbrains.com/help/youtrack/standalone/youtrack-markdown-syntax-issues.html) using parsing expression grammars. The Markdown implementation in YouTrack follows the [CommonMark specification](https://spec.commonmark.org/0.29/) with extensions. Thus, `jira2markdown` can be used to convert text to any Markdown syntax with minimal modifications.
# Table of Contents
* [Prerequisites](#prerequisites)
* [Installation](#installation)
* [Usage](#usage)
* [Conversion tables](#conversion-tables)
* [Headings](#headings)
* [Text Effects](#text-effects)
* [Text Breaks](#text-breaks)
* [Links](#links)
* [Lists](#lists)
* [Images](#images)
* [Tables](#tables)
* [Advanced Formatting](#advanced-formatting)
* [Customization](#customization)
# Prerequisites
- Python 3.7+
# Installation
```
pip install jira2markdown
```
# Usage
```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
```
# 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
<table>
<tr>
<th>Jira</th>
<th>Markdown</th>
</tr>
<tr>
<td>
```
* some
* bullet
** indented
** bullets
* points
```
</td>
<td>
```
- some
- bullet
- indented
- bullets
- points
```
</td>
</tr>
<tr>
<td>
```
# a
# numbered
# list
```
</td>
<td>
```
1. a
1. numbered
1. list
```
</td>
</tr>
<tr>
<td>
```
# a
# numbered
#* with
#* nested
#* bullet
# list
```
</td>
<td>
```
1. a
1. numbered
- with
- nested
- bullet
1. list
```
</td>
</tr>
<tr>
<td>
```
* a
* bulleted
*# with
*# nested
*# numbered
* list
```
</td>
<td>
```
- a
- bulleted
1. with
1. nested
1. numbered
- list
```
</td>
</tr>
</table>
## Images
<table>
<tr>
<th>Jira</th>
<th>Markdown</th>
</tr>
<tr>
<td>
```
!image.jpg!
!image.jpg|thumbnail!
!image.gif|align=right, vspace=4!
```
</td>
<td>
```
```
</td>
</tr>
<tr>
<td>
```
!image.jpg|width=300, height=200!
```
</td>
<td>
```
<img src="image.jpg" width="300" height="200" />
```
</td>
</tr>
</table>
## Tables
<table>
<tr>
<th>Jira</th>
<th>Markdown</th>
</tr>
<tr>
<td>
```
||heading 1||heading 2||heading 3||
|col A1|col A2|col A3|
|col B1|col B2|col B3|
```
</td>
<td>
```
|heading 1|heading 2|heading 3|
|-|-|-|
|col A1|col A2|col A3|
|col B1|col B2|col B3|
```
</td>
</tr>
</table>
## Advanced Formatting
<table>
<tr>
<th>Jira</th>
<th>Markdown</th>
</tr>
<tr>
<td>
```
{noformat}
preformatted piece of text
so *no* further _formatting_ is done here
{noformat}
```
</td>
<td>
````
```
preformatted piece of text
so *no* further _formatting_ is done here
```
````
</td>
</tr>
<tr>
<td>
```
{panel:title=My Title}
Some text with a title
{panel}
```
</td>
<td>
```
> **My Title**
> Some text with a title
```
</td>
</tr>
<tr>
<td>
```
{code:xml}
<test>
<another tag="attribute"/>
</test>
{code}
```
</td>
<td>
````
```xml
<test>
<another tag="attribute"/>
</test>
```
````
</td>
</tr>
</table>
# Customization
To customize the list of markup elements send it as an optional argument to `convert`:
```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)
```
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:
```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)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/catcombo/jira2markdown",
"name": "jira2markdown",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "jira,markdown",
"author": "Evgeniy Krysanov",
"author_email": "evgeniy.krysanov@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/fd/41/611ce8fbceb5b76ddcafc003e797a72436f32954617e59ec5f1b55218fbc/jira2markdown-0.3.6.tar.gz",
"platform": null,
"description": "# Overview\n\n`jira2markdown` is a text converter from [JIRA markup](https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all) to [YouTrack Markdown](https://www.jetbrains.com/help/youtrack/standalone/youtrack-markdown-syntax-issues.html) using parsing expression grammars. The Markdown implementation in YouTrack follows the [CommonMark specification](https://spec.commonmark.org/0.29/) with extensions. Thus, `jira2markdown` can be used to convert text to any Markdown syntax with minimal modifications.\n\n# Table of Contents\n\n * [Prerequisites](#prerequisites)\n * [Installation](#installation)\n * [Usage](#usage)\n * [Conversion tables](#conversion-tables)\n * [Headings](#headings)\n * [Text Effects](#text-effects)\n * [Text Breaks](#text-breaks)\n * [Links](#links)\n * [Lists](#lists)\n * [Images](#images)\n * [Tables](#tables)\n * [Advanced Formatting](#advanced-formatting)\n * [Customization](#customization)\n\n# Prerequisites\n\n- Python 3.7+\n\n# Installation\n\n```\npip install jira2markdown\n```\n\n# Usage\n\n```python\nfrom jira2markdown import convert\n\nconvert(\"Some *Jira text* formatting [example|https://example.com].\")\n# >>> Some **Jira text** formatting [example](https://example.com).\n\n# To convert user mentions provide a mapping Jira internal account id to username \n# as a second argument to convert function\nconvert(\"[Winston Smith|~accountid:internal-id] woke up with the word 'Shakespeare' on his lips\", {\n \"internal-id\": \"winston\",\n})\n# >>> @winston woke up with the word 'Shakespeare' on his lips\n```\n\n# Conversion tables\n\n## Headings\n\n| Jira | Markdown |\n|------|----------|\n|`h1. Biggest heading`|`# Biggest heading`|\n|`h2. Bigger heading`|`## Bigger heading`|\n|`h3. Big heading`|`### Big heading`|\n|`h4. Normal heading`|`#### Normal heading`|\n|`h5. Small heading`|`##### Small heading`|\n|`h6. Smallest heading`|`###### Smallest heading`|\n\n## Text Effects\n\n| Jira | Markdown |\n|------|----------|\n|`*strong*`|`**strong**`|\n|`_emphasis_`|Not converted (the same syntax)|\n|`??citation??`|`<q>citation</q>`|\n|`-deleted-`|`~~deleted~~`|\n|`+inserted+`|`inserted`|\n|`^superscript^`|`<sup>superscript</sup>`|\n|`~subscript~`|`<sub>subscript</sub>`|\n|`{{monospaced}}`|`` `monospaced` ``|\n|`bq. Some block quoted text`|`> Some block quoted text`|\n|`{quote}Content to be quoted{quote}`|`> Content to be quoted`|\n|`{color:red}red text!{color}`|`<font color=\"red\">red text!</font>`|\n\n## Text Breaks\n\n| Jira | Markdown |\n|------|----------|\n|`\\\\`|Line break|\n|`---`|`\u2014`|\n|`--`|`\u2013`|\n\n## Links\n\n| Jira | Markdown |\n|------|----------|\n|`[#anchor]`|Not converted|\n|`[^attachment.ext]`|`[attachment.ext](attachment.ext)`|\n|`[http://www.example.com]`|`<http://www.example.com>`|\n|`[Example\\|http://example.com]`|`[Example](http://example.com)`|\n|`[mailto:box@example.com]`|`<box@example.com>`|\n|`[file:///c:/temp/foo.txt]`|Not converted|\n|`{anchor:anchorname}`|Not converted|\n|`[~username]`|`@username`|\n\n## Lists\n\n<table>\n<tr>\n<th>Jira</th>\n<th>Markdown</th>\n</tr>\n<tr>\n<td>\n\n```\n* some\n* bullet\n** indented\n** bullets\n* points\n```\n</td>\n<td>\n\n```\n- some\n- bullet\n - indented\n - bullets\n- points\n```\n</td>\n</tr>\n<tr>\n<td>\n\n```\n# a\n# numbered\n# list\n```\n</td>\n<td>\n\n```\n1. a\n1. numbered\n1. list\n```\n</td>\n</tr>\n<tr>\n<td>\n\n```\n# a\n# numbered\n#* with\n#* nested\n#* bullet\n# list\n```\n</td>\n<td>\n\n```\n1. a\n1. numbered\n - with\n - nested\n - bullet\n1. list\n```\n</td>\n</tr>\n<tr>\n<td>\n\n```\n* a\n* bulleted\n*# with\n*# nested\n*# numbered\n* list\n```\n</td>\n<td>\n\n```\n- a\n- bulleted\n 1. with\n 1. nested\n 1. numbered\n- list\n```\n</td>\n</tr>\n</table>\n\n## Images\n\n<table>\n<tr>\n<th>Jira</th>\n<th>Markdown</th>\n</tr>\n<tr>\n<td>\n\n```\n!image.jpg!\n!image.jpg|thumbnail!\n!image.gif|align=right, vspace=4!\n```\n</td>\n<td>\n\n```\n\n```\n</td>\n</tr>\n<tr>\n<td>\n\n```\n!image.jpg|width=300, height=200!\n```\n</td>\n<td>\n\n```\n<img src=\"image.jpg\" width=\"300\" height=\"200\" />\n```\n</td>\n</tr>\n</table>\n\n## Tables\n\n<table>\n<tr>\n<th>Jira</th>\n<th>Markdown</th>\n</tr>\n<tr>\n<td>\n\n```\n||heading 1||heading 2||heading 3||\n|col A1|col A2|col A3|\n|col B1|col B2|col B3|\n\n```\n</td>\n<td>\n\n```\n|heading 1|heading 2|heading 3|\n|-|-|-|\n|col A1|col A2|col A3|\n|col B1|col B2|col B3|\n```\n</td>\n</tr>\n</table>\n\n## Advanced Formatting\n\n<table>\n<tr>\n<th>Jira</th>\n<th>Markdown</th>\n</tr>\n<tr>\n<td>\n\n```\n{noformat}\npreformatted piece of text\n so *no* further _formatting_ is done here\n{noformat}\n```\n</td>\n<td>\n\n````\n```\npreformatted piece of text\n so *no* further _formatting_ is done here\n```\n````\n</td>\n</tr>\n<tr>\n<td>\n\n```\n{panel:title=My Title}\nSome text with a title\n{panel}\n```\n</td>\n<td>\n\n```\n> **My Title**\n> Some text with a title\n```\n</td>\n</tr>\n<tr>\n<td>\n\n```\n{code:xml}\n <test>\n <another tag=\"attribute\"/>\n </test>\n{code}\n```\n</td>\n<td>\n\n````\n```xml\n <test>\n <another tag=\"attribute\"/>\n </test>\n```\n````\n</td>\n</tr>\n</table>\n\n# Customization\n\nTo customize the list of markup elements send it as an optional argument to `convert`:\n```python\nfrom jira2markdown import convert\nfrom jira2markdown.elements import MarkupElements\nfrom jira2markdown.markup.links import Link\nfrom jira2markdown.markup.text_effects import Bold\n\n# Only bold and link tokens will be converted here\nelements = MarkupElements([Link, Bold])\nconvert(\"Some Jira text here\", elements=elements)\n```\n\nKeep in mind that the order of markup elements is important! Elements are matching first from top to bottom in the list.\n\nTo override some elements in the default element list use `insert_after`/`replace` methods:\n```python\nfrom jira2markdown import convert\nfrom jira2markdown.elements import MarkupElements\nfrom jira2markdown.markup.base import AbstractMarkup\nfrom jira2markdown.markup.links import Link\nfrom jira2markdown.markup.text_effects import Color\n\nclass CustomColor(Color):\n ...\n\nclass MyElement(AbstractMarkup):\n ...\n\nelements = MarkupElements()\nelements.replace(Color, CustomColor)\nelements.insert_after(Link, MyElement)\nconvert(\"Some Jira text here\", elements=elements)\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Convert text from JIRA markup to Markdown using parsing expression grammars",
"version": "0.3.6",
"project_urls": {
"Homepage": "https://github.com/catcombo/jira2markdown",
"Repository": "https://github.com/catcombo/jira2markdown"
},
"split_keywords": [
"jira",
"markdown"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ce08ab86f842b4c19be4881381addbf5b9053d379705cd70dd6a58e8a22f2527",
"md5": "6db75493cae624867899faa7867d4358",
"sha256": "d894815100147381a1684acfce13dc332bf9db3dfd3b7de7b9dc332d9321c275"
},
"downloads": -1,
"filename": "jira2markdown-0.3.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6db75493cae624867899faa7867d4358",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 14326,
"upload_time": "2023-07-30T15:25:40",
"upload_time_iso_8601": "2023-07-30T15:25:40.929886Z",
"url": "https://files.pythonhosted.org/packages/ce/08/ab86f842b4c19be4881381addbf5b9053d379705cd70dd6a58e8a22f2527/jira2markdown-0.3.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "fd41611ce8fbceb5b76ddcafc003e797a72436f32954617e59ec5f1b55218fbc",
"md5": "8778d3a0bb517e78f11464e532f3812b",
"sha256": "b014aafff46be65439339130d8413e1f17558dcb66051c77d519e30a3304e19f"
},
"downloads": -1,
"filename": "jira2markdown-0.3.6.tar.gz",
"has_sig": false,
"md5_digest": "8778d3a0bb517e78f11464e532f3812b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 11657,
"upload_time": "2023-07-30T15:25:43",
"upload_time_iso_8601": "2023-07-30T15:25:43.075954Z",
"url": "https://files.pythonhosted.org/packages/fd/41/611ce8fbceb5b76ddcafc003e797a72436f32954617e59ec5f1b55218fbc/jira2markdown-0.3.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-30 15:25:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "catcombo",
"github_project": "jira2markdown",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "jira2markdown"
}
JSON
