撰写内容

Markdown 和 HTML 格式

DevSite 上的大部分内容都是以 Markdown 格式编写的，这是一种旨在实现纯文本的简洁性和可读性的写作格式。DevSite 会自动将 Markdown 转换为 HTML 以便在网络上显示。

如需了解常见 HTML 元素的 Google 特有 Markdown 等效项，请参阅 go/g3mark-cheat 中的速查表。如需查看 Google 的 Markdown（也称为 CommonMark）的完整文档，请点击此处。

以下是几个例子：

何时使用 HTML 而不是 Markdown

我们不会使用 Markdown 编写某些内容，包括：

• 包含文件：所有包含文件都应该是 HTML 文件，因此不应包含以 Markdown 编写的任何元素。如需有关创建包含文件的指导，请参阅在多个页面中重复使用内容。

• 表格：Markdown 表格可能难以设置格式和维护，因此即使在 Markdown 文件中，我们也使用 HTML 来处理表格。

• 图片：使用 HTML 处理图片可让图片格式和放置位置更加灵活。请参阅 DevSite 发布指南中的图片部分。

• Zippies：Zippies（在 Devsite 上称为可展开的 widget）必须采用 HTML 格式，并封装在 <div> 标记中。

常见内容格式

在新标签页中打开的链接

请遵循链接指南，了解何时应在同一标签页中打开链接，何时应在新标签页中打开链接。如果您需要在新标签页中打开链接，可以按以下方式设置链接格式：

Markdown

[Accessible content](/style/accessibility){:target="_blank"} 

HTML

<a href="/style/accessibility" target="_blank">Accessible content</a>

表格

如需了解 DevSite 提供的表格类型及其对应的 HTML，请参阅 DevSite 发布指南中的表格。

提示：

• 如果您需要表格没有边框，请使用 class="columns"

• 如果您需要表格具有内边距和分隔线（如此网页），请使用 class="columns extra-padding"，并在内容行之间的单独行中使用 <hr> 标记。

展开式主题

对于 Workspace，我们使用 arrow-icon 类来设置 zippy 的样式。以下是 Workspace 的压缩 widget（可展开的 widget）示例：

<div>
  <devsite-expandable class="arrow-icon" id="UNIQUE_ZIPPY_ID">
    <h4 class="showalways">ZIPPY_HEADING</h4>
    <div>
      YOUR_CONTENT
    </div>
  </devsite-expandable>
</div>

如需使用此示例，请替换以下变量：

• UNIQUE_ZIPPY_ID：输入一个描述性且唯一的 ID，以便您可以直接指向 zippy，例如 direct-admin-access。
• ZIPPY_HEADING：输入用户在展开 zippy 之前应看到的文字。
• YOUR_CONTENT：输入用户在展开 zippy 时应看到的内容。

如需详细了解 DevSite 的可展开 widget，请参阅 DevSite 发布指南中的微件：可展开部分。

包含共享内容

如需在多个网页中重复使用内容，您可以使用包含项，这是 DevSite 版本，相当于在 Composer 的多篇文章中使用代码段。

如需有关创建包含文件并在内容中使用包含的指南，请参阅在多个页面中重复使用内容。

向标题添加自定义锚点

DevSite 会为每个标题创建一个 HTML ID 属性。为确保标题更改时的一致性，您可以在标题文本旁边添加 {:#your-id}，为标题添加自定义锚点 ID，例如：

## Apply filters to your search results {:#apply-filters}

提示：如需为文件中的所有标题自动创建自定义锚 ID，请按 Command (\⌘) + H（在 Windows 上，按 Ctrl + H）。现有的自定义锚 ID 不会发生变化。

如需了解详情，请参阅有关标题 ID 的 DevSite 发布指南。