自动文档检查

命令行工具 doc-checker 会对文档进行多项检查 来源。不需要访问外部链接的检查会以 将更改提交到 //docs 目录时进行提交前检查。

文档检查工具的主要目标是确保 //docs 中的所有文档 目录是互连图的一部分，该图由 _toc.yaml 个文件和 当相关文档是在 fuchsia.dev.其他检查会检查链接本身，以强制执行文档 标准和一致性。

运行文档检查工具

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 fragment 文件

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> - （可选） 缩进目录条目，用于定义 可收起的部分，通常通过 include 另一个 _toc.yaml 文件进行定义。
    • 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（包含在 从根目录 _toc.yaml 创建的目录图， //docs/_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 的结构

TBD：__driversepitaphs.yaml 的用途是什么？

_problems.yaml 的结构

待定：_problems.yaml 有何用途？

结构 of_redirects.yaml

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

_supported_cpu_architecture.yaml 的结构

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

_supported_sys_config.yaml 的结构

支持的系统配置列表。

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

结构 of_tools.yaml

TBD：tools.yaml 的用途是什么？

请参阅：源代码

结构 of_已弃用-docs.yaml

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

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

_glossary.yaml 的结构

此文件定义了 Fuchsia 术语表。

请参阅：添加术语表术语

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

为 Google 托管的网站添加 hl 参数

hl 参数指示用户的主机语言。此参数应 不包含在网址中，因为它会禁止自动重定向到 翻译后的网页（如果有的话）。