在Azure DevOps的工作项中使用markdown

发布于:2025-07-28 ⋅ 阅读:(19) ⋅ 点赞:(0)

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语言。

    image

  • 在弹出的窗口中,我们可以看到系统自动将HTML转换为Markdown语言,你可以在页面中预览markdown语言渲染的显示效果;

    image

  • 点击上图中的转换按钮(Convert),富文本框中的描述就会被替换为markdown语言编写的内容;同时,富文本编辑器也会切换为mardown语言编辑器。
    保持工作项后,这个字段的markdown内容就会存储到服务器中。

    image

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. 备注

    1. 特别复杂格式的富文本
      对于特别复杂格式的富文本内容,建议保留HTML语言,因为Markdown语言并不能全部的网页展现形式;例如,如浮动元素、多列排版、自定义样式、按钮、表单、嵌入 iframe 或脚本等。
    1. 不能转回HTML
      当某个特定工作项中的富文本字段转换为Markdown语言后,你不能再次转回HTML;当然,并不影响其他工作项中的富文本字段类型,其他工作项仍然可以使用HTML语言存储富文本。
    1. 只能用于富文本字段
      Markdown语言只能用于存储富文本的字段(例如描述、重新步骤、验收标准等),不能用于当行文本类型的字符字段。

https://www.cnblogs.com/danzhang
Azure DevOps MVP 张洪君

image


网站公告

今日签到

点亮在社区的每一天
去签到