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 toHTML
, 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.
Any option to convert this enmasse?
No plans to provide an option to change all work items over to use Markdown. You can use the REST APIs though if you really to update all the existing work items.
See the “Using REST APIs” section above.
Hi, Dan!
Could you advise us on the approach to safely mass-update certain fields (like Description, Acceptance Criteria, Repro Steps, Comments, and History) to markdown via API?Nevermind, got it already 🙂 Managed to update everything except Comments (System.History) 👍
Is it possible to get the rendered HTML text for the current markdown content for the large text fields, same as we get in the comments where if pass the expand param renderText then it returns the corresponding HTML data for the current markdown content.
No, sorry, you can pull the content and render on your own. But we don’t have any special API param that will take the Markdown content and return it as HTML.
Shouldn’t it be included in the API response, as it will be very much helpful. And no data loss or corruption would occur if Microsoft itself provides the rendered HTML content, so that the behavior is consistent for both Comments and Work item fields data
If we have integrations creating work items, can we update the rest call to include the
"/multilineFieldsFormat/System.Description"
value now, and it ignore it if not enabled, or will it cause an error if not yet rolled out?I’m also wondering because that would be a great addition to the
azure-devops-mcp
project, but if rollout is weeks and would cause error, then it’s not something that could be added until it’s GA for everyone.it’s already added to the MCP project. I think it will error out if the org is not on markdown yet.
This is amazing news which was a blocker longtime to adoption amongst those favouring markdown. Wondering how would custom fields behave when contained in a WI? Would be great to be able to do a full proper consolidated Markdown (we wanted to generated static web sites with structured content)
Custom fields are supported as long as they are large text fields. The small single line text fields are not supported.
Great news! Does this also include mermaid support?
Looks really good.
Saldy no Mermaid Support
Also HTML Checkboxes don´t get converted from HTML to MD
This is coming soon