文档样式指南

本文档提供了 Fuchsia.dev 的写作风格指南。这些指南以 [Google Developers 文档风格指南][google-dev-doc-style-guide] 中的一般指南为基础。

  • 如需了解一般文档标准（包括文件类型、位置和一般语气），请参阅 [Fuchsia 文档标准][doc-standard]。
  • 如需了解有关字词选择、风格和结构的具体指南，请参阅 [Fuchsia 文档风格指南][style-guide]。
  • 如需查看完整的 Markdown 参考指南，请参阅 [Markdown 参考指南][markdown-guide]。

文本和链接

遵循 80 个字符的限制

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

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

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

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

请注意外部链接图标：这是一个 [外部][external-link-example]{:.external} 链接。

一般来说，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 指南][markdown-reference-links]。

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

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

  • /docs/ - 链接到 Fuchsia 源代码树的 /docs/ 目录中的文档。这些链接必须链接到扩展名为 .md 的文件。例如，/docs/concepts/README.md。

  • 源代码 - 链接到 Fuchsia 源代码树中存在的源代码文件。这些链接可以链接到任何文件扩展名，但这些文件必须存在于源代码树中。例如，/sdk/lib/fdio/fdio.cc。

  • 参考文档 - 链接到自动生成的 Fuchsia 参考文档。

    • 大多数 Fuchsia 参考文档都不存在于源代码树中，而是发布在 [fuchsia.dev][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}

代码示例

对 Shell 命令示例使用 posix-terminal

建议：在 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]
[sh]: https://cs.opensource.google/fuchsia/fuchsia/+/main:/zircon/system/ulib/inspect/include/lib/inspect/cpp/vmo/state.h

[doc-standard]: /docs/contribute/docs/documentation-standards.md [style-guide]: /docs/contribute/docs/documentation-style-guide.md [markdown-guide]: /docs/contribute/docs/markdown.md [google-dev-doc-style-guide]: https://developers.google.com/style [markdown-reference-links]: /docs/contribute/docs/markdown.md [external-link-example]: http://example.com [fuchsia-dev]: https://fuchsia.dev