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.9+
Command line tool
Use pipx to install to isolated environment.
pipx install jira2markdown
There are multiple ways to use command line tool:
- Provide text to convert as an argument:
jira2markdown "{quote}So many books, so little time{quote}"
- Specify path to a file containing Jira markup text:
jira2markdown -f path/to/file.txt
- Use result of another command as an input:
echo "{quote}So many books, so little time{quote}" | jira2markdown
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 |
---|---|
|
|
|
|
|
|
|
|
Images
Jira | Markdown |
---|---|
|
|
|
|
Tables
Jira | Markdown |
---|---|
|
|
Advanced Formatting
Jira | Markdown |
---|---|
|
|
|
|
|
|
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
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file jira2markdown-0.5.tar.gz
.
File metadata
- Download URL: jira2markdown-0.5.tar.gz
- Upload date:
- Size: 12.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/2.1.2 CPython/3.12.9 Linux/6.13.11-100.fc40.x86_64
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
396690965833234e6f7001e8c2dd3934cdee963ffe8a885cfb3cbe309121e810
|
|
MD5 |
2a9c94061673c0fde6f72432d8ccefe5
|
|
BLAKE2b-256 |
69fd22635ac878174973a016e1acdd9252e3dafd6a54e64487a8d7479ec4acfc
|
File details
Details for the file jira2markdown-0.5-py3-none-any.whl
.
File metadata
- Download URL: jira2markdown-0.5-py3-none-any.whl
- Upload date:
- Size: 15.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/2.1.2 CPython/3.12.9 Linux/6.13.11-100.fc40.x86_64
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 |
2a9145f7ec4eeddb164586509074f2588aeb18e87adf99d303642bb3c90cb6c4
|
|
MD5 |
7158cdf501d11fbbee4944cdcaf3ddda
|
|
BLAKE2b-256 |
4eb5d0bb59abbfca5226311756bf4ea3ec31e5fefd0a8ab0a7f534f8a35c7f84
|