Markdown Support Arrives for Work Items

Dan Hellem

Product Manager for Azure Boards

After several months in private preview and many bug fixes along the way, we’re excited to announce that Markdown support in large text fields is now generally available! 🎉

🦄 How it works

By default, all existing and new work items will continue using the HTML editor for large text fields. However, you now have the option to opt-in and use the Markdown editor for individual work items and fields.

Existing work items

Open the work item and click into a large text field (e.g., Description). The field will initially appear as an HTML editor, but you’ll now see an option to convert it to Markdown.

We perform a best-effort conversion of the HTML to Markdown.

Keep in mind, the more complex the HTML, the harder it is to accurately convert it. If your field contains intricate formatting, we recommend keeping it in HTML.

⚠️ Important

Once you convert a field to Markdown, there’s no way to revert it back to HTML.

After the conversion takes place, the work item will display the text in Markdown format whenever you edit it.

You can also toggle a preview mode to see how your Markdown renders in real time.

New work items

For new work items, the experience is similar, except there is no existing data to convert.

Also, your editor preference is sticky. Meaning, if you choose Markdown for a new work item, we’ll remember your preference, and all future work items you create will default to Markdown.

If you prefer HTML for a particular field, you can select it, as long as the field is still empty.

Once a field is being used in Markdown mode, the HTML editor is no longer available. However, if you paste HTML into the editor, we’ll attempt to automatically convert it to Markdown.

🧑‍💻 Using REST APIs

When creating a work item through the REST API’s the default format for any large text field will remain HTML. However, you can set the format to Markdown by adding an additional operation to your patch document. Here is an example to set the System.Description field to Markdown:

{ 
  "op": "add",
  "path": "/fields/System.Description",
  "value": "# some markdown text"
},
{ 
  "op": "add",
  "path": "/multilineFieldsFormat/System.Description",
  "value": "Markdown"
},

The /multilineFieldsFormat setting can be used with any large text field to enable Markdown formatting.

Here are the key rules when using the REST API:

The default format is HTML
Once a work item is saved with Markdown, it cannot be reverted back to HTML, just like in the UI
This setting only applies to large text fields such as Description, Repro Steps, and Acceptance Criteria. Custom large text fields are also supported

🚀 Release process

As part of our improved release process, we’ve introduced additional checks to ensure a smooth rollout, which means it may take a bit longer to reach everyone.

The rollout began this week with the first group of customers. We typically allow a few days between each wave to monitor for any issues before proceeding to the next group. The rollout is divided into five stages (which we call “rings”), and we expect the full deployment to all organizations to take approximately 4 to 5 weeks.

💬 Feedback

We hope you enjoy the new Markdown support for large text fields in work items. If you have feedback or encounter any issues, please don’t hesitate to submit a ticket. Our team actively monitors incoming reports and will respond accordingly.