Convert Jira markup to markdown

[maltoe]

👋 I would really like to be able to take the description from Jira tickets and copy it to commit messages.

[pmeinhardt]

Did some quick research 🔎 and some more digging in my 🧠…

Atlassian markup format

There's some more information on the Jira markup syntax here:
https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all

Not a formal specification, but I hope this gives a good overview of the syntax.

Get fields as HTML from API

There could be another pointer here:
https://docs.atlassian.com/software/jira/docs/api/REST/7.6.1/#expansion

The Jira API can apparently return markup fields rendered to HTML via "expansion".
You just append ?expand=renderedFields to the issue URL.

Maybe the HTML can be converted to a plain-text or markdown description more reliably.

Drill open one of the Atlassian client packages?

There is a page listing a lot of Atlassian's software packages from their so-called "atlaskit":
https://atlaskit.atlassian.com/packages

Maybe there's something that can help us?

Get ADF format & render that?

I checked the network tab and it looks like (the hosted Jira at least) now has and uses a GraphQL API which returns values as ADF (Atlassiant Document Format).

Maybe it'd be possible to convert this structured representation into a commit-compatible text-format more easily?

[klappradla]

Maybe the HTML can be converted to a plain-text or markdown description more reliably.

Briefly looked into this topic yesterday as well. I think the HTML -> Markdown is a very promising approach 👍

[pmeinhardt]

Looks like showdown can convert HTML to markdown:
https://github.com/showdownjs/showdown/blob/1.9.1/src/converter.js#L346-L352

Gave it a quick try.

Grab the HTML description from the rendered fields:
https://<workspace>.atlassian.net/rest/api/latest/issue/<issue-id>?expand=renderedFields

Install showdown:

yarn add showdown

Then, in node:

// Showdown requires a browser-like environment, so we use JSDOM here
const { JSDOM } = require("jsdom");
const { window } = new JSDOM("");
const { document } = window; 

const { Converter } = require("showdown");

const converter = new Converter();

const html = `…`;

console.log(converter.makeMarkdown(html));

Already spotted some problems though:

• monospaced (e.g. code) content is rendered as <tt>…</tt> which is just passed through by Showdown 🔥
• the markdown output for Atlassians "smart links"™️ looks odd
• …

Showdown supports custom extensions, but it sounds like another 🐇🕳️

[pmeinhardt]

What if we just convert to plain-text though @maltoe and @klappradla?

const { JSDOM } = require("jsdom");
const { window } = new JSDOM(html);
console.log(window.document.body.textContent)

This seems to work well. It does mean however that you lose links, code block delimiters… all that. Lists are likely to be a problem too, so I'm not sure whether it's an improvement over the current behavior, just passing through the markup.

In Tickety-Tick itself we wouldn't need JSDOM (we're already in a browser context).
This is just so you can run examples in a Node.js REPL.

[klappradla]

What if we just convert to plain-text though?

I'd personally actually be in favor of that 👍. It make less assumptions about the workflows of people.

[pmeinhardt]

Okay, I think I've found the way forward:

1. Use API v3 when fetching issue details
   • This will use the new Atlassian Document Format (ADF) to return fields containing markup
   • I tried and just switching from the current /rest/api/latest (see source), to /rest/api/3 does the trick.
   • https://developer.atlassian.com/cloud/jira/platform/rest/v3/api-group-issues/#api-rest-api-3-issue-issueidorkey-get
2. Transform ADF to an mdast tree
3. Use mdast-util-to-markdown to serialize the tree to markdown
4. 🍰 ☕