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

Question

如何在 Microsoft VSTS 中将包含多行单元格的表格添加到 markdown？

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

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

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

我通过markdown-it 库发现另一个页面显示they use commonmark。

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

答：不，VS Code 使用 CommonMark Markdown 规范 降价它库。 GitHub 正在走向 CommonMark 您可以在此更新中阅读的规范。

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

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

我必须手动重新添加标题。 我目前的绊脚石是多行单元格。 Github 支持网格表， 见Newline in markdown table?:

+---------------+---------------+--------------------+
| 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 的链接并将其添加到上面。我在那里提出了an issue 以进行澄清（或增强）。目前尚不清楚 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 是一个带有严格spec 的 Markdown 变体。 GitHub-Flavored Markdown (GFM) 是 CommonMark 的扩展（它为 CommonMark 添加了表格等功能），有自己的spec。因此，说一个实现支持 GFM 就是说它支持带有扩展的 CommonMark。请注意 GitHub adopted the current spec 于 2017 年 3 月 14 日，因此任何较早的信息可能与当前实施无关。

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

GFM 规范的Tables section 明确指出：

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

并给出这个简单的例子：

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

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

潘多克

Pandoc supports 多种不同风格的表格语法。如果您将 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.

请注意，Pandoc 的gfm 变体使用Pipe Tables。还值得注意的是，由于 GitHub 采用了 Commonmark，Pandoc 的 markdown_github 变体已被弃用。但即使是markdown_github 变体也使用管道表。

Pandocs 的管道表状态文档（已添加重点）：

管道表的单元格不能包含段落和列表等块元素，并且不能跨越多行。

并给出这个例子：

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

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

VSTS

VSTS Documentation for Tables 在此示例中与 GFM 和 Pandoc 管道表非常匹配：

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

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

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

结论

鉴于上述情况，要被 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 ...）。

Answer 2

VSTS的markdown不支持，我在这里提交用户声音：multi-line in the cell of a table in markdown in VSTS，你可以投票关注。