說明文件樣式指南

本文提供 Fuchsia.dev 的寫作風格指南。這些指南以 [Google Developers Style Guide][google-dev-doc-style-guide] 中的一般指南為基礎。

  • 如要瞭解一般文件標準 (包括檔案類型、位置和一般語氣)，請參閱 [Fuchsia 文件標準][doc-standard]。
  • 如需字詞選擇、樣式和結構方面的具體指引，請參閱 [Fuchsia 文件樣式指南][style-guide]。
  • 如需完整的 Markdown 參考指南，請參閱 [Markdown 參考指南][markdown-guide]。

文字和連結

遵守 80 個半形字元的限制

在 Fuchsia 專案中，程式碼的行長度上限為 100 個字元，文件則為 80 個字元。這項規則的例外情況是網址 (即連結)，這類內容會寫在一行，不會換行。

程式碼通常會縮排 (頁面左側的空白空間)，而英文散文 (文件) 則通常會形成文字段落。這項差異會導致寬度規格不同。

使用 {:.external} 標記不在 fuchsia.dev、fuchsia.googlesource.com 或 fuchsia-review.googlesource.com 內的任何連結：

This is an [external](http://example.com){:.external} link.

請注意外部連結圖示：這是 [外部][external-link-example]{:.external}連結。

一般來說，Fuchsia 建議在 Markdown 檔案中使用參照樣式的連結。 參照樣式連結會使用與連結相關聯的參照 ID，然後在文件中使用連結時參照該 ID。這樣一來，您就能輕鬆更新文件中的連結。

建議：在您要連結的位置建立 ID。

在本範例中，連結 ID 名為 fuchsia-home：

Welcome to the [Fuchsia home page][fuchsia-home].

接著在文件底部定義：

[fuchsia-home]: https://fuchsia.dev/

不建議：撰寫內嵌連結，如下所示：

Welcome to the [Fuchsia home page](www.fuchsia.dev).

如要進一步瞭解參考樣式連結，請參閱外部的 [Markdown 指南][markdown-reference-links]。

使用正確的連結前往不同的 Fuchsia 內容

在 Fuchsia 文件中，您可以連結至三種內容：

  • /docs/ - 連結至 Fuchsia 來源樹狀結構 /docs/ 目錄中的文件。這些連結必須指向副檔名為 .md 的檔案。例如：/docs/concepts/README.md。

  • 原始碼 - 連結至 Fuchsia 原始碼樹狀結構中的原始碼檔案。這些連結可以連結至任何副檔名，但這些檔案必須存在於來源樹狀結構中。例如：/sdk/lib/fdio/fdio.cc。

  • 參考文件 - 自動生成的 Fuchsia 參考文件連結。

    • 大部分的 Fuchsia 參考文件都不在來源樹狀結構中，而是發布在 [fuchsia.dev][fuchsia-dev]。這些連結必須使用完整網址，例如 https://fuchsia.dev/reference/fidl/fuchsia.io。
    • 不過，來源樹狀結構中仍有一些 Fuchsia 參考文件。這些文件位於 /docs/reference/，並發布在「https://fuchsia.dev/fuchsia-src/reference/」部分。這些連結必須連結至副檔名為 .md 的檔案。例如：/docs/reference/fidl/bindings/overview.md。

建立有效的 Markdown 文件後，請執行 doc-checker，確保文件使用有效的連結。當您嘗試提交包含 .md 檔案的變更時，Gerrit 會執行 doc-checker，如果連結失效，系統就會封鎖提交作業。

如要在本機執行 doc-checker，請使用 fx format-code 工具：

fx format-code

標頭

網頁和章節標題應採用句首字母大寫格式

建議：使用句首字母大寫格式。

# This title is an example of sentence case

不建議使用：使用首字大寫：

# This Title is an Example of Title Case

錨點請使用連字號，不要使用底線

根據預設，fuchsia.dev 會使用底線 (_) 取代空格來建立錨點。如要參照網頁中的某個區段，請使用破折號 (-) 建立自訂錨點，而非 {#section-title}。此外，檔案名稱也請使用連字號。

建議：使用破折號做為錨點

 ## This is a section header {#this-is-a-section-header}

程式碼範例

使用 posix 終端機執行殼層指令範例

建議：在殼層指令的 ``` 後方新增 posix-terminal，讓讀者輕鬆複製程式碼區塊中的內容。

```posix-terminal
fx ota
```

這個程式碼區塊會以指令開頭的 $ 算繪：

fx ota

不建議：請勿在指令中硬式編碼 $ 字元。

$ fx ota

如要停用複製功能，請選取「無」

建議做法：在 ``` 後方加入 none {:.devsite-disable-click-to-copy}，適用於不需要讀者複製內容的程式碼或輸出範例。

```none {:.devsite-disable-click-to-copy}
$ my_command
It won't be necessary to copy and paste this code block.
```

這個程式碼區塊會顯示，但右上角不會有複製圖示：

$ my_command
It won't be necessary to copy and paste this code block.

不建議的做法：為僅供檢視的內容啟用複製功能。如果 ``` 後方未指定任何內容，系統會預設啟用複製功能。

```
$ my_command
It won't be necessary to copy and paste this code block.
```

這個程式碼區塊的轉譯結果如下：

$ my_command
It won't be necessary to copy and paste this code block.

參照原始碼時，請使用路徑而非網址

建議：凡是參照原始碼的連結，都應只參照路徑。否則會收到靜態錯誤檢查。

Update the [state header][sh]
[sh]: https://cs.opensource.google/fuchsia/fuchsia/+/main:/zircon/system/ulib/inspect/include/lib/inspect/cpp/vmo/state.h

[doc-standard]：/docs/contribute/docs/documentation-standards.md [style-guide]：/docs/contribute/docs/documentation-style-guide.md [markdown-guide]：/docs/contribute/docs/markdown.md [google-dev-doc-style-guide]：https://developers.google.com/style [markdown-reference-links]：/docs/contribute/docs/markdown.md [external-link-example]：http://example.com [fuchsia-dev]：https://fuchsia.dev