Markdown editor for comments (preview)

Dan Hellem

We are delighted to announce the long-awaited private preview of the new Markdown editor for the work item discussion. This exciting feature empowers you to utilize the Markdown syntax and editor for all future comments. The Markdown editor aligns with the same experience you encounter in other parts of the product, such as Pull Requests.

Existing comments

You have the option to keep your existing work item comments as they are or convert them individually to Markdown. Our migration process makes a best effort to convert the HTML to Markdown, and in the majority of cases, it works as expected. However, it’s important to note that the conversion may not always achieve 100% accuracy for large, complex comments that contain custom styles.

Image markdown

New comments

With the new Markdown editor, you can anticipate the following:

  • Support for all of the essential Markdown formats. To explore further, you can learn more about Markdown.
  • Smooth conversion of HTML tables or tables copied from emails into Markdown format. While we do a best effort conversion, please note that certain table formats may not achieve 100%.
  • Use the <mark>value</mark> syntax for string highlighting.
  • Continued support for @mentions and !mentions.

New Boards Hub only

The Markdown editor is exclusively available through the New Boards Hub. It is important to note that certain scenarios may result in a less than ideal experience for users who are not enrolled in the New Boards Hub. For instance, if a comment is created in the New Boards Hub and a user opens that particular work item in the Old Boards Hub, the comment will display the Markdown syntax. If you are going to enroll in this preview, it is highly recommended that all users make use of the New Boards Hub.

Once you have enrolled in the preview, you cannot revert back to the old experience that uses HTML for comments.

It is important to note that this new Markdown editor for comments will replace the current HTML editor in the New Boards Hub. Once the feature is generally available, it will be the only editor for comments moving forward.

Enroll in the private preview

The intent of the private preview is to get customer feedback before the feature can be made generally available. If you are interested in enrolling in the private preview, please send us email and include your organization name (https://dev.azure.com/{organization}). Note that the preview is limited, and we will be capping the number of organizations who can participate.

We are excited to finally make this feature available and we hope you love it as much as we do.

14 comments

Discussion is closed. Login to edit/delete existing comments.

  • Michael Taylor 0

    I’m a little confused as to the impact of markdown in work items for those not participating. I tend to enable and use preview features long before anyone on my team does. Most of them are not yet even using the new board hub UI because of the concurrency update issues.

    What I’m not clear on is the impact of using MD for those not participating. The blog mentions that you’ll see MD if you aren’t using the new UI and I’m fine with that. They are already used to seeing MD with wikis and whatnot. But if our organization is in the preview then does everyone starting using MD now or do we still need to flip the preview feature at the user level? Normally we allow users to enable preview features on their own and don’t mandate anything. I can see some users sticking with HTML (because they copy from documents and whatnot) so I don’t want to force everyone to use MD just because I want to preview the feature.

    • Dan HellemMicrosoft employee 0

      Hello Michael.

      Couple of things.

      1) It would be good to send specifics on the “Most of them are not yet even using the new board hub UI because of the concurrency update issues.”. We have about 20k users on New Boards Hub today and not getting any reports of this issue.

      2) This feature is an all or nothing for the Markdown editor. It affects the entire organization. Meaning, when we turn it your org, every user using the New Boards Hub will now start using the Markdown editor for comments. This feature was too complicated to allow opt-in at the user level. Also note, that once we turn it on in your org, there is no going back. You can’t turn it off and go back to the HTML editor.

      • Michael Taylor 0

        1) I already reported it to you way back in the first days of the new UI and on most iterations since then. The issues are around work items having links added/removed/updated from external actions (pushing a commit, merging a branch, changing the state of a child work item, etc) and the parent work item failing to allow changes without refreshing the UI because it detects external changes. This has been (and continues to be) a problem since the new hub UI was released.

        2) I’ll have to talk to my team then since everyone is comfortable with MD but I’m not sure if everyone wants to commit to it at this point. I definitely do as it is easier to work with but we have active work items using HTML formatting that won’t work anymore. Thanks for this information.

        • Dan HellemMicrosoft employee 0

          Please email me directly if you are still experiencing issues.

  • Svante Svenson 0

    Hi Dan.

    Will this affect how the comments are stored and exposed in the APIs, or is it just the editor that gets changed and the comments rendered into HTML before being stored? Asking since I’m reading the last comment in an Power Automate flow and try to parse the text…

    • Michael Taylor 0

      Markdown can be converted to HTML but not vice versa. Therefore I would expect the markdown to be stored, not the converted HTML. If it converted to HTML then there would be no way to get back to the markdown that produced it. Just my opinion.

    • Dan HellemMicrosoft employee 1

      We don’t render them into HTML on storage. They are stored as Markdown and returned as Markdown via API. The UI then displays as HTML.

  • Sebastian Schütze 0

    With the new adjustment. We will have a problem with the Azure Boards Teams app. By default it is suggesting HTML used in the teams app. If Markdown will be activated for work items I worry that the teams Integration for Azure Boards will stop working properly. Any plans to update this as well?

    • Dan HellemMicrosoft employee 0

      Teams supports Markdown already so it should not be an issue.

  • Björn Jarisch 0

    Are there any plans to bring markdown support to other work item text fields such as the Description? It would be great to be able to have a table in a work item that can be edited by multiple users, which doesn’t work with the old editor due to lack of editable table support, and doesn’t work with the new Markdown comments because users can’t edit each other’s comments. Right now our workaround is to maintain such tables in a wiki and have the work item point to the corresponding wiki page which is not ideal froma workflow standpoint.

    • Dan HellemMicrosoft employee 1

      Our plan is to release the markdown for discussions first. That will go out as we turn on New Boards Hub for all customers. Then we will shift our focus and enable Markdown for large text fields like Description. I don’t yet have a timeline, but we hope it will happen in early 2024.

  • Michael Eilers 1

    Hello,

    It appears I am somehow in this preview, although I did not opt in, nor did my team make any new boards. Other members of the team can look at the same story as myself, and they see the styled text editor (HTML) while I see the Markdown discussion fields. How is this possible?

    I work with a mixed team of developers, business and QA. They are DEEPLY unhappy with this change and do not want to learn Markdown, and prefer to remain with the styled editor as it is similar to Word and you can copy/paste from Word to there and retain styles. Will there be an option to opt out? This seems highly unwise to inflict Markdown on non-devs who see no value in learning it.

    Reading back through these posts, my organization will definitely default to the NOTHING of the “all or nothing” approach to this change. How do we ensure this does not happen for our org?

    • Dan HellemMicrosoft employee 2

      Sorry Michael. Let me address a couple of your issues

      “It appears I am somehow in this preview, although I did not opt in, nor did my team make any new boards. Other members of the team can look at the same story as myself, and they see the styled text editor (HTML) while I see the Markdown discussion fields. How is this possible?”

      New Boards and Markdown are in the process of rolling out to ALL organizations. It is a change that is coming for everyone, it just depends on where your instance is located. All organizations will eventually be on the New Boards and Markdown for discussions.

      Existing comments will not be converted to Markdown unless someone specifically converts that comment. But all new Comments will use Markdown. It is also possible that some people have gone in and turned off New Boards Hub. Turning it off is only possible for the next couple of months. We don’t recommend this as the New Boards Hub is the future. Old boards will get removed in early 2024.

      “I work with a mixed team of developers, business and QA. They are DEEPLY unhappy with this change and do not want to learn Markdown, and prefer to remain with the styled editor as it is similar to Word and you can copy/paste from Word to there and retain styles. Will there be an option to opt out? This seems highly unwise to inflict Markdown on non-devs who see no value in learning it.”

      Azure DevOps is a developer tool. Although we understand that not everyone is a developer that uses it. We have received a significant number of requests asking to enable Markdown in text fields to match the industry standard.

      The Markdown editor will still allow you to cut and paste HTML. And the Editor has commands to do common editing tasks if someone is not familiar with Markdown.

      “Reading back through these posts, my organization will definitely default to the NOTHING of the “all or nothing” approach to this change. How do we ensure this does not happen for our org?”

      Unfortunately, there is no way to opt-out. Your organization will be onboarded, if not already. It might be good to give your users a quick intro to Markdown. We are happy to send you some resources if that helps.

      • Michael Eilers 0

        Thank you for your answers, I will share them with my team.

Feedback usabilla icon