自動化說明文件檢查

指令列工具 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 來源樹狀結構中，已併入 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> - (選用) 縮排的目錄項目，定義可收合的區段，通常是透過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 中根 _toc.yaml 建立的目錄圖表中。

_areas.yaml 的結構

待定：__「_areas.yaml」的結構為何？_

__eng_council.yaml 的結構

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

__metadata.yaml 的結構

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

_rfcs.yaml 的結構

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

請參閱 RFC 中繼資料。

Structure of_roadmap.yaml

待定：__roadmap.yaml 的用途為何？__

Structure of_drivers_areas.yaml

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

__drivers_epitaphs.yaml 的結構

待定：__driversepitaphs.yaml? 的用途為何？

Structure of_problems.yaml

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

_redirects.yaml 的結構

這個檔案會針對指定網址定義重新導向至其他網頁。

__supported_cpu_architecture.yaml 的結構

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

Structure of_supported_sys_config.yaml

支援的系統設定清單。

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

_tools.yaml 的結構

待定：__What is the use of tools.yaml?__

請參閱：原始碼

_deprecated-docs.yaml 的結構

這個檔案會定義已淘汰文件的重新導向規則。

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

__glossary.yaml 的結構

這個檔案定義了 Fuchsia 術語的詞彙表。

請參閱：新增詞彙表字詞

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

包括 Google 代管網站的 hl 參數

hl 參數表示使用者的主機語言。請勿在網址中加入這個參數，因為這樣會停用自動重新導向至翻譯網頁 (如有)。