文档样式指南

本文档提供了 Fuchsia.dev 的编写样式指南。这些指南基于 Google Developers 样式指南中的常规指南。

文字和链接

遵循 80 个字符的长度限制

在 Fuchsia 项目中，代码行的长度上限为 100 个字符，而文档的行数上限为 80 个字符。此规则的一个值得注意的例外情况是网址（即链接）写在一行上，不换行。

代码倾向于采用缩进格式（页面左侧的空白区域），而英文散文（文档）则倾向于形成文本段落。这种差异导致宽度规范不同。

使用 {:.external} 标记 fuchsia.dev、fuchsia.googlesource.com 或 fuchsia-review.googlesource.com 以外的任何链接：

This is an [external](http://example.com){:.external} link.

请注意外部链接图标：这是一个外部链接。

通常，Fucchsia 建议在 Markdown 文件中使用引用样式链接。引用样式链接使用与链接关联的参考标识符，然后每当您在文档中使用链接时都会引用该标识符。这样，您就可以轻松在文档中更新链接。

建议：在您希望建立链接的位置创建标识符。

在此示例中，关联标识符称为 fuchsia-home：

Welcome to the [Fuchsia home page][fuchsia-home].

然后在文档底部对其进行定义：

[fuchsia-home]: https://fuchsia.dev/

不推荐：编写如下所示的内嵌链接：

Welcome to the [Fuchsia home page](www.fuchsia.dev).

如需详细了解引用样式链接，请参阅外部 Markdown 指南。

使用指向不同 Fuchsia 内容的正确链接

在 Fuchsia 文档中，您可以链接到三种类型的内容：

  • /docs/ - 指向 Fuchsia 源代码树 /docs/ 目录中的文档的链接。这些链接必须链接到扩展名为 .md 的文件。例如 /docs/concepts/README.md。
  • 源代码 - 指向 Fuchsia 源代码树中存在的源代码文件的链接。这些链接可以链接到任何文件扩展名，但这些文件必须位于源代码树中。例如，/sdk/lib/fdio/fdio.cc。
  • 参考文档 - 自动生成的 Fuchsia 参考文档的链接。
    • 大多数 Fuchsia 参考文档都不存在于源代码树中，但会发布在 fuchsia.dev 上。这些链接必须用作完全限定的网址。例如 https://fuchsia.dev/reference/fidl/fuchsia.io。
    • 不过，源代码树中存在一些 Fuchsia 参考文档。这些文档位于 /docs/reference/ 中，并在 https://fuchsia.dev/fuchsia-src/reference/ 部分发布。这些链接必须链接到扩展名为 .md 的文件。例如 /docs/reference/fidl/bindings/overview.md。

创建有效的 Markdown 文档后，您应运行 doc-checker 以确保您的文档使用有效的链接。当您尝试提交包含 .md 文件的更改时，Gerrit 会运行 doc-checker，如果链接已损坏，则会阻止提交。

如需在本地运行 doc-checker，请使用 fx format-code 工具：

fx format-code

标头

为网页和版块标题采用句首字母大写形式

建议：采用句首字母大写形式。

# This title is an example of sentence case

不建议：使用词首字母大写：

# This Title is an Example of Title Case

使用短划线（而不是下划线）作为锚点

默认情况下，fuchsia.dev 使用下划线 (_) 代替空格来创建锚点。引用网页中的部分时，请改用短划线 (-) 和 {#section-title} 创建自定义锚点。此外，文件名也请使用短划线。

建议：使用短划线表示锚点

 ## This is a section header {#this-is-a-section-header}

代码示例

使用 posix-terminal 查看 shell 命令示例

推荐做法：在 ``` 后为 shell 命令添加 posix-terminal，以便读者轻松复制代码块中的内容。

```posix-terminal
fx ota
```

此代码块通过在命令前面使用 $ 来呈现：

fx ota

不建议：不要在命令中对 $ 字符进行硬编码。

$ fx ota

使用“无”以停用复制功能

建议：对于不需要读取器复制内容的代码或输出示例，请在 ``` 之后添加 none {:.devsite-disable-click-to-copy}。

```none {:.devsite-disable-click-to-copy}
$ my_command
It won't be necessary to copy and paste this code block.
```

此代码块在渲染时右上角没有复制图标：

$ my_command
It won't be necessary to copy and paste this code block.

不推荐：为“只能查看”的内容启用复制功能。如果您在 ``` 之后未指定任何内容，系统会默认启用复制功能。

```
$ my_command
It won't be necessary to copy and paste this code block.
```

此代码块呈现如下：

$ my_command
It won't be necessary to copy and paste this code block.

在引用源代码时使用路径而不是网址

建议：任何引用源代码的链接都应仅使用路径来引用。否则，将出现静态错误检查。

Update the [state header][sh]