說明文件樣式指南

本文提供 Fuchsia.dev 的寫作風格指南。這些指南以 Google 開發人員樣式指南中的一般指南為基礎。

文字和連結

遵守 80 個半形字元的限制

在 Fuchsia 專案中，程式碼的最大行長度為 100 個半形字元，而說明文件的最大行長度為 80 個半形字元。這項規則的一個顯著例外狀況是，網址 (即連結) 會寫在一行，且不會換行。

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

使用 {:.external} 標示不在 fuchsia.dev、fuchsia.googlesource.com 或 fuchsia-review.googlesource.com 中的連結：

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

請注意外部連結圖示：這是外部連結。

一般來說，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 指南。

使用正確的 Fuchsia 內容連結

在 Fuchsia 說明文件中，您可以連結至三種類型的內容：

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

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

  • 參考說明文件 - 自動產生的 Fuchsia 參考說明文件連結。

    • 大部分的 Fuchsia 參考說明文件並未位於來源樹狀結構中，而是發布在 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 可停用複製功能

建議：如果程式碼或輸出範例不需要讀者複製內容，請在 ``` 後方加上 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]