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.
Great to see that the feature is rolling out. What’s the rollout schedule for Azure DevOps Server 2022?
TBD. The problem is that this feature depends on New Boards Hub. We have not figured out the timeline for New Boards rollout with on-prem. We want it to bake a little longer in the service as it is a lot easier to fix issues in the service than on-prem.
This is a great add!
I’ve been waiting for this for a long time. So this is great news, thanks Dan.
How do I use this via Azure Devops Cli btw?
Dan,
We received markdown support for the description field today. Thanks!
We have an issue to report. When you click on the description field's scroll bar, the field switches to edit mode which is very annoying. I would say a majority of the time, our users are simply reading work item description fields and not modifying them. Luckily, the mouse wheel does scroll the field while remaining in preview mode.
We would prefer the field only switch to edit mode when the user clicks on the text of the field and not the scrollbar.
Thanks,
This is by design and is necessary unless we add an Edit/Preview toggle on the control. We elected that when you click into it, it switches to edit mode. But you can still stay in preview mode and click on links or checkboxes. We will keep an eye on the feedback and if we get more folks reporting an issue, we can make a change.
Thanks a lot for this feature. Like Mike, we vote for an edit button too, allowing to select rendered text directly.
Dan,
Thanks for the quick reply. We vote for the edit button.
Thanks.
Hey!
This is such a great feature and we’ve been waiting for something like this for a long time, to help us overcome the many formatting issues we come across with ADO boards.
However as it stands this feature is unusable for us, as we rely heavily on templates for our stories.
Do we have any idea on when/if this will be something that’s improved upon, so that maybe we can set this as the default for all PBIs/work items and therefore also allow our templates to work?
Many thanks!
Ben
This is a really great feature and we can use it as it is but, unfortunately, there's a similar pain-point for us.
All we need is to add line breaks in our work item templates but neither "backslash n backslash n" nor "space space backslash n" work in the new Markdown renderer (they just render verbatim) therefore we have to use "br elements" and that means when a new item loads, the new Markdown renderer sees those "br elements" markup and decides it's HTML and we have to convert each field manually. Not the biggest of problems I face in life...
Hey Dan. This is great, I’m using it already.
Do we have a way to support saving the work item template in markdown as well? I’m trying it (with the capture template feature), but it seems to save it in a single line, unformatted.
Cheers,
Daniel
Is the release process still running? We do not have access to markdown in my org yet (I can’t wait 😅)
Yes, there were a couple of bugs discovered and we needed to pause the rollout to the last set of customers. I am hoping we can enable by early next week.
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-mcpproject, 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.