自动文档检查

命令行工具 doc-checker 会对文档来源执行多项检查。在向 //docs 目录提交更改时，不需要访问外部链接的检查会作为预提交检查执行。

文档检查工具的主要目标是确保 //docs 目录中的所有文档都属于由 _toc.yaml 文件组成的互联图，并且当文档发布到 fuchsia.dev 上时，页内链接可访问。其他检查会检查链接本身，以强制执行文档标准并确保一致性。

运行 doc-checker

fx doc-checker

添加 --local-links-only 可跳过外部链接检查。

如需了解更多选项，请参阅完整的命令行参考文档。

如果它因某种原因未包含在当前 build 配置中，请重新运行 fx set，包括用于构建 doc_checker 的选项：--with //tools/doc_checker:doc_checker。

以下是文档检查器报告的情况：

[missing doc](/docs/does_not_exist.md)

这些链接引用 fuchsia.googlesource.com 或 fuchsia.dev，并访问 //docs 中的文件。这些链接应转换为文件路径。

不正确

[unnessary link](https://fuchsia.dev/fuchsia-src/get-started/learn-fuchsia.md)

正确

[correct link](/docs/get-started/learn-fuchsia.md)

这些是包含在 Fuchsia 源代码树中、已合并到 Fuchsia 或已完全弃用的项目。有效项目的列表是源代码的一部分。


     [invalid old project](https://fuchsia.googlesource.com/garnet/+/refs/heads/main)

这些链接指向 //docs 目录之外的路径。这些路径应转换为 fuchsia 相对路径。

不正确

  [source file](/docs/../src/BUILD.gn)

正确

   [source file](https://cs.opensource.google/fuchsia/fuchsia/+/main:/src/BUILD.gn)

图片缺少 alt 文本

图片必须包含有意义的alt文字。

![Diagram of the state transitions](/docs/state-machine.png "State machine")

包括 Markdown 片段文件

使用以下语法将 Markdown 文件片段包含在另一个 Markdown 文件中：

<<relative-path-to/_file.md>>

路径必须相对于当前的 .md 源文件，不能使用绝对路径。<< >> 指令属于块指令，因此必须单独显示在一行中。

YAML 数据文件检查

fuchsia.dev 中的 YAML 文件用于以结构化格式存储文档内容，然后通过使用 Jinja 模板呈现这些内容。以 _ 为前缀的任何 YAML 文件都表示该 YAML 不会作为独立文件发布，而只会通过使用模板进行渲染。如果 YAML 文件未以 _ 为前缀，则该 YAML 文件会发布到 fuchsia.dev，并且可以作为纯 YAML 文件查看。

_toc.yaml 检查

_toc.yaml 文件主要用于为 fuchsia.dev 创建信息架构。

这些检查会强制执行 _toc.yaml 参考文档中所述的目录结构。

  • 顶级键 toc

  • 条目可以是以下任一值：

    • break: true - （可选）添加竖线分隔符
    • contents: <list of toc entries> - （可选）自定义标签页的内容。
    • heading: <string> - （可选）一组链接的标题。
    • include: <path to _toc.yaml> - （可选）包含另一个 _toc.yaml。
    • name: <string> - （可选）相应标签页的名称。
    • path: <string> - （可选）网页的路径或网址。
    • path_attributes: <mapping> - （可选）根据 path 属性创建的链接的属性名称-值对。
    • section: <toc entry> - （可选）缩进的目录条目，用于定义可折叠的部分，通常通过另一个 _toc.yaml 文件（include）定义。
    • skip_translation: true - （可选）禁止人工和机器翻译相应条目及其所有后代中的所有链接标题。
    • status: <string> - （可选）与 heading 或 title 搭配使用，不能与 break 或 include 搭配使用。应用预定义的状态。状态必须是以下值之一：
    • alpha
    • beta
    • deprecated
    • experimental
    • external
    • limited
    • new
    • step_group: <string> - （可选）用于创建具有 prev 和 next 导航链接（位于页面底部）的内容组。
    • style: <string> - （可选） 不能与 break 或 include 一起使用。 此样式应用于 heading 或 section 元素。此值必须为 accordion。
    • title: string - （可选）链接标题。

  • path 属性是有效路径：

    • 文件路径，例如 /docs/somewhere/file.md
    • http:// 或 https:// 网址。
    • /reference 到生成的参考文档。这些链接通过指向 fuchsia.dev/reference 的外部链接进行验证。
    • 特殊文件：/CONTRIBUTING.md 和 /CODE_OF_CONDUCT.md。

_toc.yaml 图中未引用的网页

//docs 中的 Markdown 页面必须出现在 _toc.yaml 中，该 包含在根据 //docs/_toc.yaml 中根 _toc.yaml 创建的目录图表中。

_areas.yaml 的结构

待定：_areas.yaml__ 的结构是什么

_eng_council.yaml 的结构

待定：_eng_council.yaml 的用途是什么？

_metadata.yaml 的结构

待定：_metadata.yaml 的用途是什么？_

_rfcs.yaml 的结构

此文件定义了 RFC 文档的元数据。

请参阅 RFC 元数据。

_roadmap.yaml 的结构

待定：_roadmap.yaml 有何用途？_

_drivers_areas.yaml 的结构

待定：_drivers_areas.yaml的用途是什么？

_drivers_epitaphs.yaml 的结构

待定：__driversepitaphs.yaml 的用途是什么？

_problems.yaml 的结构

待定：_problems.yaml 有什么用途？_

_redirects.yaml 的结构

此文件定义了给定网址到另一网页的重定向。

_supported_cpu_architecture.yaml 的结构

待定：_What is the use of _supported_cpu_architecture.yaml?

supported_sys_config.yaml 的结构

支持的系统配置列表。

请参阅支持的系统配置列表

of_tools.yaml 的结构

待定：_tools.yaml 的用途是什么？_

请参阅：源代码

_deprecated-docs.yaml 的结构

此文件定义了已弃用文档的重定向规则。

请参阅：将网页重定向到弃用通知。

_glossary.yaml 的结构

此文件定义了 Fuchsia 术语的词汇表。

请参阅：添加术语库术语

    [broken link](https://mispeeled.com)

包括适用于 Google 托管网站的 hl 参数

hl 参数表示用户的宿主语言。此参数不应包含在网址中，因为如果存在翻译后的网页，此参数会停用自动重定向到翻译后网页的功能。