自動化說明文件檢查

指令列工具 doc-checker 會對說明文件執行多項檢查 來源。不需要存取外部連結的功能會依照 提交變更至 //docs 目錄時，預先提交檢查。

文件檢查工具的主要目標是確認 //docs 中的所有文件 目錄是互連圖表的一部分，由 _toc.yaml 個檔案與 我們可在相關說明文件發布 fuchsia.dev.其他檢查會檢查連結本身，以便強制執行說明文件 標準和一致性

執行文件檢查工具

fx doc-checker

新增 --local-links-only 即可略過外部連結檢查。

如要進一步瞭解這些選項，請參閱完整指令列參考資料。

如果因故未納入目前的建構設定， 重新執行 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 來源樹狀結構中的專案， 或已合併完成有效專案清單 是原始碼的一部分


     [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 檔案片段會透過

<<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 從根目錄 _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 的結構

待定：___driversepitaphs.yaml 的用途為何？

problems.yaml 的結構

待定：_problems.yaml 的用途為何？_

_redirects.yaml 的結構

這個檔案定義了特定網址的重新導向行為。

_supported_cpu_frameworkure.yaml 的結構

待定：__supported_cpu_architecture.yaml的用途為何？

_supported_sys_config.yaml 的結構

支援的系統設定清單。

請參閱支援的系統設定清單

_tools.yaml 的結構

待定：_tools.yaml 的用途為何？_

請參閱：原始碼

已淘汰-docs.yaml 的結構

此檔案定義了已淘汰文件的重新導向規則。

請參閱「將網頁重新導向至淘汰通知」一節。

_glossary.yaml 的結構

此檔案提供 Fuchsia 術語的定義。

請參閱：新增詞彙表字詞

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

為 Google 代管網站加入 hl 參數

hl 參數代表使用者的主機語言。這個參數應該 未包含網址，因為它會停用重新導向至 以及翻譯過的網頁