如何使用 Markdown 来撰写文档

您所在的位置：网站首页 › md文档怎么写接口文档 › 如何使用 Markdown 来撰写文档

如何使用 Markdown 来撰写文档

2024-07-17 20:40| 来源: 网络整理| 查看: 265

在以下三种主要情况下应该使用 HTML 表格而不是 GFM 语法：

表格使用了 GFM 不支持的特性（见下文）。 GFM 表格太宽而难以阅读。使用了“属性表”这一特殊类型的表格。 GFM 不支持的表格特性

GFM 表格语法的主要限制是：

GFM 表格必须有一个标题行。 GFM 表格可能没有标题列。 GFM 不会解析单元格中的 GFM 块元素。例如，你不能在单元格中使用列表。 GFM 不支持除、、、以外的任何表格元素。 GFM 不支持诸如 colspan、rowspan、scope 等表格元素属性。

如果你需要使用任何不受支持的特性，那么应该使用 HTML 编写表格。

请注意，我们不建议在表格中经常使用元素，因为这也会无法使用 GFM 语法。

GFM 表格最大宽度

有时，即使可以使用 GFM 编写表格，也应该使用 HTML。因为 GFM 使用“ASCII art”来实现表格，当表格的一行变得过长时，将变得难以阅读。例如，考虑以下表格：

html 标题 1 标题 2 标题 3 标题 4 标题 5 标题 6 较短的内容涉及了很多细节的更长的内容，以至于表格格式在 GFM 格式中开始变得糟糕起来。较短的内容另一个包含大量文本的单元格，也涉及到了很多有关特定内容的细节，以至于表格格式在 GFM 格式中开始变得糟糕起来。较短的内容较短的内容

在 GFM 中，它会是这样：

md| 标题 1 | 标题 2 | 标题 3 | 标题 4 | 标题 5 | 标题 6 | | ---------- | ------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------------------------------------------- | ---------- | ---------- | | 较短的内容 | 涉及了很多细节的更长的内容，以至于表格格式在 GFM 格式中开始变得糟糕起来。 | 较短的内容 | 另一个包含大量文本的单元格，也涉及到了很多有关特定内容的细节，以至于表格格式在 GFM 格式中开始变得糟糕起来。 | 较短的内容 | 较短的内容 |

在这种情况下，最好使用 HTML。

所以我们遵循以下原则：如果表格的 Markdown 表示将超过 150 个字符宽度，请使用 HTML 编写。

属性表

属性表是一类特殊的表格，用于在一组特定类型的页面中显示结构化的属性值。例如，所有的 Event 页面都有一个属性表，列出了关于事件的常见信息：是否冒泡、是否可取消等等。

这类表格有两列：第一列是标题列，其列出了属性名；第二列则列出了这些特定属性的值。例如，以下是一个 PannerNode 接口的属性表：

输入数量 1 输出数量 0 通道计数模式 "explicit" 通道数 2 通道解释 "speakers"

因为它们有一个标题列，GFM 无法表示这些页面。因此，应该使用 HTML。为了获得特殊的样式，还需要将 "properties" 类应用于表格：

html

【本文地址】

如何使用 Markdown 来撰写文档

如何使用 Markdown 来撰写文档

今日新闻

推荐新闻