自動化說明文件檢查

指令列工具 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，並在 //文件中存取檔案。這些連結應轉換為檔案路徑。

答錯了

[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 檔案片段使用

<<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 項目來定義可收合區段，通常透過另一個 _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 的結構

待定：__區域.yaml__ 的結構為何

_eng_council.yaml 的結構

待定：__eng_council.yaml?

_metadata.yaml 的結構

TBD：_metadata.yaml 的用途為何？_

_rfcs.yaml 的結構

此檔案定義了 RFC 文件的中繼資料。

請參閱 RFC 中繼資料。

_roadmap.yaml 的結構

TBD：_roadmap.yaml 的用途為何？_

_drivers_areas.yaml 的結構

TBD：__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 的用途為何？_

請參閱：原始碼

淘汰文件.yaml 的結構

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

請參閱：將頁面重新導向至淘汰通知。

_glossary.yaml 的結構

此檔案定義了福奇亞術語的詞彙表。

請參閱：新增詞彙表字詞

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

在 Google 代管網站中加入 hl 參數

hl 參數代表使用者的主機語言。網址中不應包含這個參數，因為這會導致系統停止自動重新導向至翻譯網頁 (如有)。