如何将带有多行单元格的表格添加到 VSTS 中的自述文件中？

Question

如何在 Microsoft VSTS 中将带有多行单元格的表格添加到 Markdown？

我之前在 github 上使用 asciidoc 作为自述文件，因为它既丰富又不那么模糊。该公司现在在不支持 asciidoc 的 VSTS 上有项目，所以我需要改用 Markdown。但是，目前尚不清楚实际支持哪种降价方式

这个页面说可以使用github风味的markdown

https://docs.microsoft.com/en-us/vsts/collaborate/markdown-guidance

我发现另一个页面说他们通过markdown-it库使用 commonmark。

问：VS Code 是否支持 GitHub Flavored Markdown？

答：不，VS Code 使用 markdown-it 库针对 CommonMark Markdown 规范。GitHub 正在朝着 CommonMark 规范迈进，您可以在此更新中阅读该规范。

我一直在使用 asciidoctor 和 pandoc 的组合来转换文件，但没有什么能完全正确。（Asciidoctor 转换为 docbook，然后 pandoc 可以解析）

asciidoctor -b docbook -v -o "$OUTPUT".xml "$INPUT" &&
pandoc -f docbook -t markdown_github -i "$OUTPUT".xml -o "$OUTPUT"

我必须手动重新添加标题。我目前的绊脚石是多行单元格。Github 支持网格表，请参阅Markdown 表中的换行符？：

+---------------+---------------+--------------------+
| Fruit         | Price         | Advantages         |
+===============+===============+====================+
| Bananas       | first line\   | first line\        |
|               | next line     | next line          |
+---------------+---------------+--------------------+
| Bananas       | first line\   | first line\        |
|               | next line     | next line          |
+---------------+---------------+--------------------+

但是这个和嵌入的 html 似乎都不适用于 VSTS。如果允许，我很乐意改用 html 自述文件。

2017 年 11 月 17 日更新：

我找到了 markdown-it 的链接并在上面添加了它。我在那里提出了一个问题以供澄清（或增强）。目前尚不清楚 VSTS 实际使用的是哪个版本。

我想问微软自己的问题，但他们的提问链接直接进入堆栈溢出。

markdown-it 库确实支持@Waylan 建议的用法：

| Fruit         | Price                   | Advantages              |
| ------------- | ----------------------- | ----------------------- |
| Bananas       | first line<br>next line | first line<br>next line |
| Bananas       | first line<br>next line | first line<br>next line |

请参阅https://github.com/markdown-it/markdown-it/issues/406。问题很可能是 Microsoft 禁用了 html。因此，解决方案等待回复@starian 的建议：https ://visualstudio.uservoice.com/forums/330519-visual-studio-team-services/suggestions/32312290-multi-line-in-the-cell-of- a-table-in-markdown-in-v

Answer 1

简而言之，每一行必须在一行上，并且应该<br>用来表示换行。像这样：

| Fruit         | Price                   | Advantages              |
| ------------- | ----------------------- | ----------------------- |
| Bananas       | first line<br>next line | first line<br>next line |
| Bananas       | first line<br>next line | first line<br>next line |

下面是对每个工具的解释，并分析了该工具的文档：

GitHub

CommonMark是具有严格规范的 Markdown 变体。GitHub-Flavored Markdown (GFM) 是 CommonMark 的扩展（它向 CommonMark 添加了诸如表格等功能），具有自己的规范。因此，说一个实现支持 GFM 就是说它支持带有扩展的 CommonMark。请注意，GitHub在 2017 年 3 月 14 日采用了当前规范，因此任何可能与当前实现无关的旧信息。

文档中不清楚 VSTS 是实际使用 CommonMark/GFM 实现还是使用近似值。但是，由于文档明确指出支持“GitHub 风格的扩展”，这向我表明 GFM 规范将是一个很好的参考。无论如何，GFM 规范是 github.com 上呈现的任何 Markdown 的控制规范。

GFM 规范的表格部分明确指出：

不能在表中插入块级元素。

并给出了这个简单的例子：

| foo | bar |
| --- | --- |
| baz | bim |

虽然规范没有特别提到多行单元格，但没有包含多行单元格的示例。我的理解是 GFM 不支持。因此，在 GFM 表单元格中包含换行符的唯一方法是使用<br>标记，它不是块级元素。

潘多克

Pandoc支持多种不同风格的表格语法。如果您将 Markdown 传递给 Pandoc 和 GFM，那么您需要使用与 GFM 样式最匹配的 Pandoc 表格样式。例如，GFM 表不包括+对角的支持。该语法特定于 Pandoc 的Grid Tables。幸运的是，Pandoc 的文档告诉我们哪种风格最匹配 GFM。

Pandoc 支持各种“ Markdown Variants ”，其中之一是gfm. 文档有这个关于该变体的内容：

我们还支持gfm(GitHub-Flavored Markdown) 作为一组扩展commonmark：

: pipe_tables, raw_html, fenced_code_blocks, auto_identifiers, ascii_identifiers, backtick_code_blocks, autolink_bare_uris, intraword_underscores, strikeout, hard_line_breaks, emoji, shortcut_reference_links, angle_brackets_escapable.

请注意，gfmPandoc的变体使用Pipe Tables。还值得注意的markdown_github是，自 GitHub 采用 Commonmark 以来，Pandoc的变体已被弃用。但即使是markdown_github变体也使用管道表。

Pandocs 的管道表文档说明（强调）：

管道表的单元格不能包含像段落和列表这样的块元素，也不能跨越多行。

并给出了这个例子：

| Right | Left | Default | Center |
|------:|:-----|---------|:------:|
|   12  |  12  |    12   |    12  |
|  123  |  123 |   123   |   123  |
|    1  |    1 |     1   |     1  |

这显然与 GFM 表相同，并且不包括对块级元素或多行单元格的任何支持。

VSTS

表格的VSTS 文档与此示例紧密匹配 GFM 和 Pandoc 管道表：

| Heading 1 | Heading 2 | Heading 3 |  
|-----------|:---------:|----------:|  
| Cell A1   | Cell A2   | Cell A3   |  
| Cell B1   | Cell B2   | Cell B3   |

虽然 VSTS 文档没有具体提到块级元素或多行，但似乎可以安全地假设它实际上是相同的风格。

我们可以做出这个假设，因为在所有三个实例（VSTS、GFM 和 Pandoc 管道表）中，语法都没有在表的各个行之间提供分隔符（与支持行分隔符的 Pandoc 网格表相比）。虽然标题行和数据行之间有分隔线，但各个数据行之间没有分隔线，但无法指示每行有多少行文本。因此，每一行只能由一行文本表示。

结论

鉴于上述情况，要由 VSTS、GFM 和 Pandoc（gfm变体）正确解析，您的表格应格式化如下：

| Fruit         | Price                   | Advantages              |
| ------------- | ----------------------- | ----------------------- |
| Bananas       | first line<br>next line | first line<br>next line |
| Bananas       | first line<br>next line | first line<br>next line |

并且在使用 Pandoc 时，一定要使用gfm格式 ( pandoc -f gfm ...)。