Using Pandoc to convert Markdown to Jira’s Textile in Sublime Text

I use Jira a fair amount at work. It’s a very powerful software package but, unlike most of Atlassian’s other products which use Markdown, Jira uses creaky old Textile; in fact it goes further than that: it uses its own variant of creaky old Textile!

Unsurprisingly, I don’t write in Textile day-to-day:

• It’s an ancient format
• It’s more difficult to read than Markdown
• It does too much (alignment and other styling, too many text level semantics)
• It’s far from ubiquitous

On top of that, I prefer to write my tickets in my favourite text editor, Sublime Text, and copy/paste the finished ticket into Jira because:

• The tickets I write are often very long, and it isn’t fun to type directly in a <textarea>
• I can take a while to write a ticket, meaning Jira could time out and I lose my work
• If it’s an existing ticket, there’s a risk that someone else may edit the ticket description at the same time, causing a clash/conflict
• There’s no syntax highlighting in Jira’s editor

There don’t seem to be any decent Textile packages for Sublime Text (or VS Code, as far as I can tell) along the lines of the excellent MarkdownEditing and, since I prefer to write in Markdown anyway, I decided to explore the best way to:

1. Write in Markdown
2. Export my work to a Textile document (ideally the Jira variant)
3. Copy and paste the Textile code into Jira

Reader, I found it! The software that converts my Markdown documents to Jira Textile is called Pandoc.

Install Pandoc

First, we need to install the Sublime Text package, which is easy enough if you use Package Control:

1. Open the command palette with cmd + shift + p
2. Type install
3. Choose ‘Package Control: Install Package’
4. Type pandoc
5. Choose the Pandoc package that installs from https://github.com/tbfisher/sublimetext-Pandoc

Next we need to install Pandoc system-wide; as with Wget, I like to use Homebrew:

brew install pandoc

This is for macOS; the ways to install Pandoc on Windows or operating systems is different.

Configure Pandoc to convert Markdown to Jira’s Textile

Neither Textile nor the Jira’s version of Textile appear in Pandoc’s default formats, so we have to add some config for that ourselves. In Sublime Text, go to:

1. ‘Sublime Text’ in the menu bar
2. ‘Preferences’
3. ‘Package Settings’
4. ‘Pandoc’
5. ‘Settings – User’

This opens ~/Library/Application Support/Sublime Text 3/Packages/User/Pandoc.sublime-settings.

Paste the following into the empty file and save it:

{
  "user": {
    "transformations": {
      "Jira Textile": {
        "new-buffer": 1,
        "scope": {
          "text.html.markdown": "markdown"
        },
        "pandoc-arguments": [
          "--from", "markdown-auto_identifiers",
          "--to", "jira"
        ]
      }
    }
  }
}

Specifying the user object means that we don’t overwrite any default settings. We then set up a Jira transformation that tells Pandoc to:

• Identify a Markdown document
• Convert it from Markdown to Jira Textile
• Open a new file tab in Sublime Text, containing the Textile code

{
  "user": {
    "transformations": {
      "Textile": {
        "new-buffer": 1,
        "scope": {
          "text.html.markdown": "markdown"
        },
        "pandoc-arguments": [
          "--from", "markdown-auto_identifiers",
          "--to", "textile"
        ]
      },
      "Jira Textile": {
        "new-buffer": 1,
        "scope": {
          "text.html.markdown": "markdown"
        },
        "pandoc-arguments": [
          "--from", "markdown-auto_identifiers",
          "--to", "jira"
        ]
      }
    }
  }
}

Convert a Markdown file to Jira’s Textile

The first thing we need when converting a Markdown file to Textile is a Markdown document. Basically, any document that Sublime Text recognises as Markdown will do:

• A Markdown document, saved with the .md file extension
• An unsaved file that has been manually identified as Markdown via the syntax menu in:
  • The status bar’s syntax select menu
  • Sublime Text’s View menu

Once Sublime knows it’s a Markdown document:

1. Open Sublime Text’s Command Palette cmd + shift + p
2. Choose ‘Pandoc’
3. Choose ‘Jira Textile’

And that’s how you can avoid having to write Jira tickets in Textile!

Huge thanks due to Albert Krewinkel who pointed out that my original article didn’t address Jira’s version of Textile. Pandoc has an option to export in jira as well as plain old textile!

In Jira’s Textile, things like headings, lists, emphasis, and blockquotes are all the same, but certain useful things are different. I have to admit, I tended to avoid things like links and code where possible, or add them in afterwards, which was a pain:

• For links, Textile uses double quotes and a colon "Example":https://www.example.com; Jira uses braces and a pipe [Example|https://www.example.com]
• For inline code, Textile uses @ symbols @like this@; Jira uses double braces {{like this}}
• For code blocks, Textile uses bc. before the code block (or bc.. and a p. to end it); Jira uses the more sensible {code} to start and end the code block

By exporting Jira’s version directly, there’s no extra work manually adding links and code, so I can use as many as I like!