文档样式指南

本文档提供了 Fuchsia.dev 的写作风格指南。这些 指南的制定依据是 Google Developers Style 导视面板。

<ph type="x-smartling-placeholder">

文字和链接

请遵循 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).

您可以在外部 扣分指南。

使用指向不同 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 命令示例

建议：让读者轻松复制 通过在 ``` 后添加 posix-terminal 来修改代码块中的内容 获取 shell 命令。

```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]