Contents
- 1. 概述
- 2. 操作方法
- 2.1 手动更新工作项
- 2.2 使用接口更新工作项
- 3. 备注
1. 概述
Markdown 是一种轻量级的 标记语言(markup language),用于快速格式化纯文本,使其转换为结构化的 HTML 或其他富文本格式。它的设计初衷是让写作更简单、更易读,同时能轻松转换为网页内容。
在Azure DevOps中,工作项作为一种表单形式的内容管理工具,记录了大量开发过程数据。其中富文本使用图文并茂的方式存储了类似需求说明、重现过程等内容。
在之前的版本(默认设置)中,使用HTML作为富文本的语言载体,渲染富文本中的图片、表格、列表等复杂的展现形式。由于HTML是一种标记语言,在编写、识别和兼容性等方面,相对比较复杂;非技术开发人员短时间内很难掌握HTML语言。
与此对照,markdown语言具有明显的优势,它容易读写,它专注于内容、而非样式;它具有更好的兼容性,在第三方系统中能够非车容易被识别;它很容易形成版本管理、用于比对前后的差异。
由于存在这些明显的优势,在新版的Azure DevOps中,用户可以选择markdown作为富文本的记录方式;本文将为你介绍如何使用这个新的功能。
2. 操作方法
2.1 手动更新工作项
默认情况下,在Azure DevOps中的所有富文本字段,都用HTML类型的语言存储;例如,下图中的需求工作项的描述字段,就是使用HTML存储,你可以使用HTML的编辑器编辑所见即所得的内容。
在最新版本的Azure DevOps中,在富文本框的下方,你可以看到将HTML转换为Markdown语言的按钮,点击这个按钮,系统将为你把HTML转换为Markdown语言。在弹出的窗口中,我们可以看到系统自动将HTML转换为Markdown语言,你可以在页面中预览markdown语言渲染的显示效果;
点击上图中的转换按钮(Convert),富文本框中的描述就会被替换为markdown语言编写的内容;同时,富文本编辑器也会切换为mardown语言编辑器。
保持工作项后,这个字段的markdown内容就会存储到服务器中。
2.2 使用接口更新工作项
当我们使用REST Api接口来更新工作项的富文本字段时,默认语言也是HTML;
当你在调用接口的报文中添加特定的内容,就可以将HTML语言转换为Markdown,下面是一个简单的例子:
{
"op": "add",
"path": "/fields/System.Description",
"value": "# some markdown text"
},
{
"op": "add",
"path": "/multilineFieldsFormat/System.Description",
"value": "Markdown"
},
在上面的例子中,multilineFieldsFormat用于设定描述字段(System.Description)的存储格式为Markdown语言。
3. 备注
-
- 特别复杂格式的富文本
对于特别复杂格式的富文本内容,建议保留HTML语言,因为Markdown语言并不能全部的网页展现形式;例如,如浮动元素、多列排版、自定义样式、按钮、表单、嵌入 iframe 或脚本等。
- 特别复杂格式的富文本
-
- 不能转回HTML
当某个特定工作项中的富文本字段转换为Markdown语言后,你不能再次转回HTML;当然,并不影响其他工作项中的富文本字段类型,其他工作项仍然可以使用HTML语言存储富文本。
- 不能转回HTML
-
- 只能用于富文本字段
Markdown语言只能用于存储富文本的字段(例如描述、重新步骤、验收标准等),不能用于当行文本类型的字符字段。
- 只能用于富文本字段
https://www.cnblogs.com/danzhang
Azure DevOps MVP 张洪君