It's not the same without you

Join the community to find out what other Atlassian users are discussing, debating and creating.

Atlassian Community Hero Image Collage

Using markdown in Jira

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

1 answer

5 votes
Daniel Eads Atlassian Team Sep 16, 2018

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.
image.pngimage.png

 

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

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:

markdown sample.png

 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)

Like # people like this

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 Atlassian Team Feb 06, 2019

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!

Like Martijn Verburg likes this

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

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

Daniel Eads Atlassian Team Feb 12, 2019

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

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.

Like # people like this

"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.

Like # people like this

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.

Like # people like this

@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?

Like Mat Chavez likes this

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.

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).

Like # people like this

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! 

Suggest an answer

Log in or Sign up to answer
Community showcase
Posted in Jira

Demo Den Ep. 7: New Jira Cloud Reports

Learn how to use two new reports for next-gen projects in Jira Cloud:  Cumulative flow diagram and Sprint burndown chart. Ivan Teong, Product Manager, Jira Software, demos the Cumulative ...

365 views 1 3
Join discussion

Community Events

Connect with like-minded Atlassian users at free events near you!

Find an event

Connect with like-minded Atlassian users at free events near you!

Unfortunately there are no Community Events near you at the moment.

Host an event

You're one step closer to meeting fellow Atlassian users at your local event. Learn more about Community Events

Events near you