md-to-jira 1.0.4rc1

Simple Python utilities for converting from GitHub-flavored Markdown syntax to Atlassian's custom markup syntax, and vice-versa

Markdown to JIRA and Confluence Markup Syntax Converter

Simple Python utilities for converting from Github-flavored Markdown syntax to Atlassian's custom markup syntax, and vice-versa. Useful for code maintainers and doc writers who use GitHub, JIRA, and Confluence.

Introduction

This is a simple Python utility to convert Markdown to JIRA and Confluence markup syntax. It is written in Python, and is designed to be used as a command line tool.

It has been purposely designed to be fully self-contained, requiring no external libraries or dependencies.

It is also designed to be easily extensible, so that it can be easily modified to support additional Markdown syntax.

Requirements

• Requires Python 3.6 or later.
• Tested on MacOS, Linux, and Windows.

Installation

Using pip (recommended)

Install from PyPI using pip:

pip install md-to-jira

The package will install two command-line tools:

• md2jira - Convert Markdown to JIRA/Confluence markup
• jira2md - Convert JIRA/Confluence markup to Markdown

From source

Alternatively, you can clone this repository and install from source:

git clone https://github.com/eshack94/md-to-jira.git
cd md-to-jira
pip install .

Legacy method (not recommended)

You can also clone the repository and run the scripts directly without installation, though this is not recommended:

python3 md_to_jira.py <file>
python3 jira_to_md.py <file>

Usage and Examples

Below are usage instructions with some simple examples. For each item, the usage syntax is first, followed by an example for illustration purposes.

Converting from Markdown to JIRA/Confluence Markup Syntax

# Convert a markdown file to Jira/Confluence markup and print to stdout
md2jira <markdown_file>
md2jira README.md

# Convert a markdown file to Jira/Confluence markup and save to a file
md2jira <markdown_file> > <jira_file>
md2jira README.md > README.jira

# Convert a markdown file to Jira/Confluence markup and copy to clipboard (MacOS)
md2jira <markdown_file> | pbcopy
md2jira README.md | pbcopy

# Convert a markdown file to Jira/Confluence markup and copy to clipboard (Linux)
md2jira <markdown_file> | xclip -selection clipboard
md2jira README.md | xclip -selection clipboard

# Convert a markdown file to Jira/Confluence markup and copy to clipboard (Windows)
md2jira <markdown_file> | clip
md2jira README.md | clip

Converting from JIRA/Confluence Markup Syntax to Markdown

# Convert a Jira/Confluence markup file to markdown and print to stdout
jira2md <jira_file>
jira2md README.jira

# Convert a Jira/Confluence markup file to markdown and save to a file
jira2md <jira_file> > <markdown_file>
jira2md README.jira > README.md

# Convert a Jira/Confluence markup file to markdown and copy to clipboard (MacOS)
jira2md <jira_file> | pbcopy
jira2md README.jira | pbcopy

# Convert a Jira/Confluence markup file to markdown and copy to clipboard (Linux)
jira2md <jira_file> | xclip -selection clipboard
jira2md README.jira | xclip -selection clipboard

# Convert a Jira/Confluence markup file to markdown and copy to clipboard (Windows)
jira2md <jira_file> | clip
jira2md README.jira | clip

Features (implemented and planned)

Current Features

• Add support for headers 1-6
• Add support for fenced code blocks
  • Do not convert headers in fenced code blocks
• Add support for indented code blocks
  • Do not convert headers in indented code blocks
• Add support for inline code (backticks) - should be converted to JIRA's monospace syntax
• Add support for bold text
• Add support for italic text
• Add support for strikethrough text
• Add support for unordered lists
• Add support for in-line style links
• Add support for task lists
  • Note: Added, but this is not supported by JIRA native markup and requires a JIRA plugin to work
• Add jira_to_md.py to convert JIRA/Confluence markup to GitHub-flavored Markdown (GFM)

Feature Roadmap

• Add support for tables
• Add support for horizontal rules
• Add support for ordered lists
• Add support for blockquotes
• Add support for images
• Add support for emojis
• Add support for in-line style links with titles (if possible)
• Add support for reference style links
• Add support for inline HTML
• Add unit tests
  • Add unit tests for md_to_jira.py
  • Add unit tests for jira_to_md.py
• Maybe: Add argparse support for command line options
• Other TBD

Housekeeping action items

• Add GitHub Actions config to run unit tests, flake8 linting, and other checks
• Refactor and clean up code once all basic features are implemented
• Enforce branch protection rules after setting up GitHub Actions and adding unit tests
  • Require status checks to pass before merging
  • Require pull requests to be reviewed and approved before merging
  • Require branches to be up to date before merging
  • Add git tags for releases

Why did I start this mini-project?

This project was created as a way to avoid having to use Atlassian's custom markup syntax.

I wanted to be able to write Confluence documentation and JIRA updates using Github-flavored Markdown, and then have a simple way to convert it without having to use an online converter, browser extension, or any third-party libraries or dependencies.

Additional Resources

• Markdown Cheatsheet
• GitHub Flavored Markdown Spec
• Atlassian Text Formatting Notation Help
• Confluence Wiki Markup