文档样式指南

本文档提供了 Fuchsia.dev 的编写风格指南。这些指南基于 Google 开发者编写风格指南中的一般指南。

文字和链接

字符数不得超过 80 个

在 Fuchsia 项目中，代码的行长度上限为 100 个字符，文档的行长度上限为 80 个字符。这条规则的一个显著例外情况是，网址（即链接）写在一行内，不会换行。

代码通常会缩进（页面左侧留有空白），而英语散文（文档）通常会形成文本段落。这种差异会导致宽度规范不同。

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

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

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

一般来说，Fuchsia 建议在 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 可停用复制功能

建议：如果代码或输出示例不需要读者复制内容，请在 ``` 后面添加 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]