說明文件樣式指南

本文件提供 Fuchsia.dev 的撰寫樣式指南。這些準則是以 Google Developers 樣式指南中的一般指南為基礎。

文字和連結

請遵循 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-terminal 做為殼層指令範例

建議：為殼層指令在 ``` 後加上 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]