Using markdown in Jira

[Nikolaj Ivancic]

After several intense years spent on Open Source projects in GitHub, I am returning to Jira (a consulting job for a customer that uses Jira everywhere) with the desire to use markdown everywhere possible (certainly in all Jira forms/fields as well as wikis). Looking around, I found several articles like this one, that are very detailed and not necessarily current.

Can someone point me to a less complicated document that would provide me with the easy way to set all renderers to markdown. At the same time, if "forcing" markdown into Jira world is unwise, please tell me why

[Daniel Eads]

Hi Nikolaj,

We're in a bit of a transition phase with our editors right now. Things to vary a bit by product at the moment.

Confluence Cloud: Markdown is supported

Confluence Server:  Out of the box, Confluence Server has some other shortcuts to do formatting but they're not necessarily markdown-syntax. There is "real" markdown support using one of several markdown apps from the Marketplace.

Jira Cloud: Support is about half and half at the moment. Places that have been ported over (mostly just looking at issues on boards at the moment) do support markdown. The "old" issue view does not currently. Right now you can tell by looking for the little Preview and "?" icons near the button to submit your comment. If there's no Preview/"?" buttons, then there is Markdown support for issue descriptions/comments in Jira Cloud.

Jira Server: On most Jira installations*, Wiki Rendering is enabled for Description and Comment fields. You can read more about the field renderers here which you may have already come across - it's also linked to in the document you listed. The Wiki Renderer uses a markdown-similar format although it's not really markdown. For example, *asterisks* around a word make it bold in Jira's wiki renderer instead of italic like Markdown specifies. On Jira 7.3 and above, you also get a Visual editor that gives you WYSIWYG if you like - you can flip between that and the Text mode which just shows you the Wiki rendering syntax by clicking the corresponding tabs at the bottom of the description/comment fields.

*if the Jira install is very old (Jira 5 or older) and has been upgraded, someone would have needed to change the field renderer to enable wiki rendering. The old versions used the Default Text Renderer for Description and Comment fields by default and this behavior wasn't overridden on upgrades.

Hope that helps!

Cheers,
Daniel

[Nikolaj Ivancic]

Thank you, Daniel, for such comprehensive answer, which should, by the way, be prominently displayed at all relevant places. The situation you described is creating me a problem - and I am quite sure Atlassian team feels the same. 

Based on your description above, I did a few tests, which warrant the subsequent question  (note that I am currently dealing with Jira and Confluence Cloud versions):

What is your definition of the term "supporting markdown"?

I tried a simple test in the comment field of a Jira issue - create a "Heading 1" line by typing the `#` character followed by a space. The editor immediately interpreted this, by deleting the `#` character and increasing the font size accordingly. I find this very confusing, as I was expecting to stay in the "markdown text entry mode" until asking for a preview or saving my text.

Then, I tried to create the markdown link - [text to display](link url) - this clearly does not work as shown below:

 Note the above screenshot represents the content of a Jira/Cloud comment on an issue (as different from being made in this editor I am using to type this text now)

[Sergei Ryabkov]

Here is more info on the new editor: https://confluence.atlassian.com/jiracorecloud/the-new-jira-issue-view-938040503.html?_ga=2.70052880.1462470402.1547742094-582225571.1540237083#ThenewJiraissueview-NewAtlassianeditor

[Martijn Verburg]

Hi @Daniel Eads - where can we track the progress on the rollout?  We're on JIRA cloud and the team is extremely excited about getting Markdown support :-).

[Daniel Eads]

Hey @Martijn Verburg- rollout of markdown in Jira Cloud is being tracked in JRACLOUD-69259. I can't share hard dates but it looks like the activity around getting it out the door is increasing. Watching that ticket is the best way to get notified when the status changes!

[Martijn Verburg]

@Daniel Eads Thanks for responding, really appreciate the link!

[Martijn Verburg]

@Daniel Eads - actually looking at  JRACLOUD-69259 - it seems to be a separate issue about wiki markup?

[Daniel Eads]

Hey @Martijn Verburg, I should have called out the discrepancy earlier. The linked issue is tracking one of the blockers for the new issue view / markdown being rolled out everywhere. You can see all the features about the new issue view in the parent ticket JRACLOUD-70555. From my understanding, JRACLOUD-69259 is one of the primary concerns blocking markdown/new issue view from being rolled out everywhere. Without fixing 69259 (the tables), existing issues with tables in wiki markdown would not render correctly and if the new issue view was forced, there would be no fallback.

It's not guaranteed that you'll be able to use markdown everywhere once 69259 is fixed, but it should definitely be fixed before markdown is available everywhere. My apologies for that being somewhat confusing! There isn't a "markdown everywhere" ticket to watch, so 69259 is the closest thing you can get to notification when it rolls out. The page @Sergei Ryabkov linked will also be updated when it rolls out everywhere, but the page update wouldn't trigger an email notification to you like Jira will.

Cheers,
Daniel

[Martijn Verburg]

@Daniel Eads Thank you kindly!

[dinbtechit]

JIRA's WYSIWYG editor is the most buggiest editor I have ever used in my entire career. Its high time they let is die peacefully and start using markdown which is more stable in my opinion. Now that we have tons of addon's for mark down.

[Ben_Kuhl]

"There isn't a "markdown everywhere" ticket to watch"

@Daniel Eads  Having such an issue would be fantastic.  We're migrating from Trello and find the lack of markdown support disappointing.

[Simon Godard]

Is there a way to let the new issue editor stay in Markdown-only mode? Having a WYSIWYG editor for Markdown is not what I want. Markdown is all about seing the markup as you are writing the content. Let me use a preview mode like GitHub editor, but let me see the raw Markdown content.

[Scott Palmer]

@Daniel Eads JRACLOUD-69259 is now closed. You previously wrote:

>JRACLOUD-69259 is one of the primary concerns blocking markdown/new issue view from being rolled out everywhere.

>It's not guaranteed that you'll be able to use markdown everywhere once 69259 is fixed, but it should definitely be fixed before markdown is available everywhere.

Will markdown support be coming to the on-premises software offerings now?

[Mat Chavez]

Basically this is a huge +1. Your on-prems are desperately missing Discount/GFM as a rendering agent. It should be a user-selected option that carries through -- a button or setting at the bottom of the text editor...  a giant M. Press it, and you get straight monospaced text that gets treated properly.

Easy as adding https://ace.c9.io/build/kitchen-sink.html and calling it a day. Preview, Save, done.

[jbeg]

Why is this only considered for Jira Cloud? We use the Jira Server and are also in need of out-of-the-box markdown support (and NOT via paid plugin).

[Tracy B]

My problem is related but not quite the same -- I have some multiline text fields that are NOT description fields, and therefore are not rich text... so no Wiki style formatting! It's very frustrating! 

[artiom.neganov]

@Daniel Eads Hi.

I wonder is markdown enabled or not? It doesn't seem that I can use any of it.

For example, I cannot even mark code as code!  It's lidicrous for a code supporting product to not provide an easy code copy-paste feature. I tried both ```...```, and {{...}}.

[artiom.neganov]

The issue mentioned above JRACLOUD-70555 hasn't been resolved yet. So... so... what the heck? Couldn't you just grab the GitHub implementation of MarkDown and be happy and make us happy?

[Daniel Eads]

Hey @artiom.neganov ,

Markdown for code blocks is supported in Jira Cloud for issues using the new issue view, as described in the information above. I've just tested against a standard Cloud site to ensure things are working as expected per the descriptions on my answer here.

It sounds like there might be a disconnect with what you're seeing. In order to best help you, I'm wondering if you could open a new question here on Community (shortcut link to ask a new question). On your question, could you please include the following:

• Confirmation if you're using Jira Cloud or Jira Server/Data Center
• Screenshot showing a failed paste attempt

Thanks, looking forward to getting this solved for you!

[john_pancoast]

@Daniel Eads I am not seeing support for Markdown code blocks in Jira. See the bottom of the attached screenshot below where neither inline code nor code blocks are rendered.

I also completely agree with @Simon Godard comment that we should be able to see markdown as we're writing it and then preview the rendered output. It is very confusing when you're writing text with and without markdown and then the markdown elements are rendered as you're typing. For example, when I typed "#" and it immediately switched my text to a large header was off-putting. It also made it confusing when I wanted to type "##" under it for a sub-header.

[Daniel Eads]

Hey John,

Thanks for including a screenshot of the paste you're seeing. I've tried reproducing this (multi-line code paste not converting) in an instance of Jira Software Cloud and didn't have success in getting the results shown in your screenshot.

In the interest of troubleshooting further, can I ask you to open either a new question we can work more thoroughly on (this link will create a new question on Community) or alternately creating a case in our support portal so we can access your Cloud instance and try and reproduce there?

Looking forward to getting this solved for you.

Cheers,
Daniel | Atlassian Support