Editing Descriptions of Jira Issues in Vim

Let’s see how to edit descriptions of Jira issues in Vim or Neovim. We will do this by installing a browser extension that can open text fields in an external editor. We will also cover how to make Jira issues syntax-highlighted in Vim, how to enable spell checking, and how to use snippets to speed up the writing of Jira issues. The approach described in the blog post can be used to edit text fields on other sites as well, such as GitHub or Stack Overflow.

Introduction

Jira is arguably one of the most commonly used issue-tracking systems, at least in the corporate world. It is essentially a web application that allows you to create, manage, and track issues (also known as tickets). To make issues more readable, Jira provides formatting support via custom syntax. However, if you are used to edit all your text in Vim (or Neovim), editing Jira issues in a text field of a web browser can be painful, especially when using the WYSIWYG editor.

Fortunately, we can use a browser extension that allows us to edit text fields in Vim, even including syntax highlighting and other goodies :-). Let’s go!

Step 1: Installing and Configuring a Browser Extension

There are various options, depending on the web browser and operating system that you use:

The Textern extension for Firefox on Linux. This is what I am using.
The chrome-bee extension for Firefox or Chrome (Chromium) on Linux, Window, or macOS.
(If you use any other extension, feel free to share it via a comment.)

Install the chosen extension and configure it to use Vim or Neovim as the external text editor. For example, here is my Textern configuration in Firefox for Neovim Qt, which is a GUI version of Neovim:

Step 2: Editing the descriptions of Jira issues in Vim

Now, you can simply click on the description of a Jira issue and use the chosen keyboard shortcut to edit it in Vim. Just do not forget to switch to the Text mode first! Here is an example of an artificial Jira issue:

And here is how it looks for me after clicking on the description in Firefox and pressing Ctrl-E:

Editing the description of a Jira issue without syntax highlighting

(Optional) Step 3: Making Syntax Highlighting Work

If you prefer to have the description of Jira issues syntax-highlighted, you can use my vim-syntax-jira plugin. After you install the plugin, you need to configure Vim to use the Jira highlighting when the opened file is a Jira issue. Here is an example of a Vimscript configuration that works for Textern (you need to replace jira.mycompany.com with the domain of your Jira instance):

" Enable Jira syntax highlighting when the opened file is created by
" https://github.com/jlebon/textern and it is a Jira issue.
let s:opened_file_path = expand('%:p')
if s:opened_file_path =~ 'textern-.*jira.mycompany.com'
  augroup firefox_textern_plugin
  autocmd!
  autocmd BufRead,BufNewFile *.txt setl ft=jira
  " (You can also set other options here.)
  augroup end
endif

The code checks whether the opened file is created by Textern and whether it is a Jira issue from jira.mycompany.com (it is based on the file-naming convention used by Textern). If both conditions are met, it sets the file type to jira to enable syntax highlighting via vim-syntax-jira.

Here is an example of how the syntax highlighting looks in my color scheme:

Editing the description of a Jira issue with enabled syntax highlighting

(Optional) Step 4: Other Goodies

Apart from syntax highlighting, you can also use other Vim features to make editing of Jira issues more pleasant. Here are some ideas:

Spell checking: You can enable spell checking via the following addition to the Vim configuration above:
```
		autocmd BufRead,BufNewFile *.txt setl spell spelllang=en
		
```
Snippets: You can use your favorite snippet engine (such as UltiSnips or LuaSnip) to speed up the writing of Jira issues. For illustration, my LuaSnip snippets for Jira are here. To give an example, if I want to insert a code block in a Jira issue, I can just write cb<tab> (“cb” stands for “code block”) and it gets expanded to the following text, where x denotes the cursor position:
```
		{noformat}
		x
		{noformat}
		
```

Other Approaches

Apart from the approach described above, there are also other ways to edit Jira issues in Vim that you can try. Here is an incomplete list:

VIRA – Creating and updating Jira issues from Vim.
jira.vim – Browsing, creating, and updating Jira issues from Vim.
Jirust – A terminal user interface for Jira.
Jirafs – Editing Jira issues using locally stored text files in a git/hg-inspired way.
jira-vim – Viewing Jira issues in Vim. (Last update: Four years ago)
vim-jira – Viewing Jira issues in Vim. (Last update: Eight years ago)
vim-jira (2) – Browsing Jira issues in Vim. (Last update: Four years ago)

Concluding Remarks

The approach described in the present blog post can be used to edit other text fields as well. For example, I use it to edit GitHub issues and pull requests, Stack Overflow questions and answers, and also the code on my website and blog.

My Vim settings are available here.

Discussion

Apart from comments below, you can also discuss this article on /r/Vim.

Petr Zemek