Closed maltoe closed 2 years ago
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?
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 👍
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:
<tt>…</tt>
which is just passed through by Showdown 🔥 Showdown supports custom extensions, but it sounds like another 🐇🕳️
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.
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.
Okay, I think I've found the way forward:
v3
when fetching issue details
/rest/api/latest
(see source), to /rest/api/3
does the trick.
👋 I would really like to be able to take the description from Jira tickets and copy it to commit messages.