說明文件樣式指南

本文件提供 Fuchsia.dev 的寫作風格指引。這些 相關規範是以 Google Developers 樣式 指南。

文字和連結

請遵守 80 個字元的限制

在 Fuchsia 專案中，代碼的長度上限為 100 個字元 而說明文件的長度上限為 80 個字元值得注意的 不過，每一行輸入的網址 (例如連結) 除外 使用非換行符號

程式碼通常會縮排 (頁面左側空白)，而英文 Prose (說明文件) 通常是以段落構成的文字。這種差異會導致 不同的寬度規格

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

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

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

一般而言，Fchsia 會建議在 Markdown 檔案中使用參照樣式連結。 參照樣式連結使用與該連結相關聯的參考 ID，以及 之後，每當使用文件的連結時，該 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 停用複製功能

建議：在 ``` 後加上 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]