文件風格指南

本指南包括有關撰寫新內容和翻譯現有內容的預期風格、MkDocs 特定語法、各種所需工具和文檔翻譯等資訊。

一般風格

• 標題和標題的第一個字應該大寫。
• 我們偏好美式拼法，但對於程式特定的口語（例如 "apps「）和名詞的動詞（例如 」scrollable"）則有一些自由度。
• artefact 「和 」artefacts "的拼寫如圖所示。
• 我們在句點後使用單個空格。
• 我們使用單一連字號並以空格包圍作為長破折號（或 HTML 中的 — 字面值）。
• 任何對產品名稱的引用都應該使用該產品名稱的首字母大寫。(例如，"macOS"、"GTK"、"pytest"、"Pygame"、"PyScript"）。
• 如果一個詞彙是 「作為代碼 」使用的，那麼它應該作為內嵌代碼引述，用單反撇(single backticks)包住它，而不是加入字典中。
• 在描述使用者應採取的行動時，我們避免使用「僅僅」、「只是」或「輕鬆」等詞彙。這些詞語可能被解讀為貶義，尤其當使用者正遭遇困難時。

交叉參考資訊

您應該盡可能交叉引用文件中的內容。本節將介紹您可以使用的各種方法，每種方法都基於被引用資訊的類型。

MkDocs 會渲染標準 Markdown 格式的連結。標準 Markdown 格式的網頁超連結如下：

[Link text](https://example.com/)

您也可以使用此格式連結到本機檔案：

[Link text](path/to/file.md)

參考檔案的特定區段或 API 文件需要使用 MkDocs 參考連結格式。

自訂 Markdown 錨點與內容交叉引用

Markdown 會根據標題的內容，為所有標題 (以一到六個 # 符號開頭的單行上的任何內容) 產生錨點。例如，本節產生的錨點是 custom-markdown-anchors-and-content-cross--referencing。然而，由於我們翻譯的工作方式，任何時候只要有節標頭被引用，就必須有自訂的錨點。

MkDocs 支援渲染參考連結語法，可讓您使用修改過的 Markdown 連結來連結到文件中的各種其他元素。這包括連結到自訂 Markdown 標題和文字錨點等。

MkDocs 參考連結是格式如下的任何連結：

[Link text][link-target]

需要自訂標題和內容錨點

在BeeWare文檔中，通過MkDocs參考鏈接在文本內容中引用的任何標題或內容部分_must_都必須附加自定義錨點。否則，在翻譯標題內容時，有可能會破壞連結。

如果您需要連結到標題錨點，您需要為目標內容產生自訂錨點。設定自訂錨點的一般語法如下：

# Header text { #anchor-name }

舉例來說，自訂此區段的錨點為 custom-anchors 就可以使用下列格式：

## Custom Markdown anchors { #custom-anchors }

您也可以在一般內容上建立錨點，包括文字和程式塊。在您想要連結的內容上方，應包含以下格式，並在上方和下方加上換行線：

Content above.

[](){ #anchor-name }

Content below, that is now attached to the anchor above.

建立自訂錨點後，您可以在同一個文件或文件的其他部分連結到這些錨點。

標準 Markdown 用來連結到_在同一個檔案_中的錨點，其格式如下：

[Link text](#anchor-name)

連結至獨立文件中的錨點使用 MkDocs 參考連結樣式，其格式如下：

[Link text][anchor-name]

API 參考連結

MkDocs 參考連結也支援交叉參考 API 文件，包括已記錄的類、類方法或屬性，以及特定的外部文件參考。

無論您是從同一個檔案或另一個檔案連結，都有多種選項可以連結到已記錄的類別、類別方法或屬性。當連結到類別等時，您必須在第一組方括弧中包含反向括號，才能將名稱呈現為內嵌程式碼。只有當您使用不應該呈現為內嵌程式碼的自訂文字時，才不需要使用反標記。切勿在第二組方括弧中加入反標記。

在顯示命名空間時連結到類別的格式如下：

[`module.ClassName`][]

在只顯示類別名稱的情況下連結至類別，其格式如下：

[`ClassName`][module.ClassName]

屬性與上述相同，並包含屬性名稱。以下顯示命名空間：

[`module.ClassName.attributename`][]

與類別一樣，只顯示屬性名稱的格式如下：

[`attributename`][module.ClassName.attributename]

方法應在名稱空間後加上 ()，因此必須以不同於屬性的方式處理。以下是連結到方法的適當方式：

[`module.ClassName.methodname()`][module.ClassName.methodname]

以下只顯示類別和方法名稱。這也需要包括名稱後的括號：

[`Classname.methodname()`][module.Classname.methodname]

您可以在顯示任意文字的同時連結到類別、方法或屬性，使用相同的方法與適用的命名空間。對一個類這樣做的格式如下：

[link text][module.ClassName]

也可以直接鏈接到 Python 核心文檔以及 Pillow 文檔。例如，連結到 int 的說明文件：

[`int`][]

連結至 Pillow Image 文件：

[`PIL.Image.Image`][]

程式碼區塊提示

語言和程式碼高亮顯示

您可以在前三個反撇號之後加上語言名稱，指定代碼區塊中所含代碼的語言，兩者之間不留空格。這會在程式碼呈現時產生適當的程式碼高亮顯示。例如，若要指定 Python，您可以用 ``python 開始程式碼區塊。

控制台指令和複製按鈕

如果您要包含主控台指令，或具有輸出的指令，如果您標示為 console 或 doscon，取決於您描述的是類似 Unix (包括 macOS) 作業系統，或是 Windows 作業系統。您可以包含作業系統提供的提示；點選複製按鈕時，只有命令會被複製。例如，如果您以 ``console 開始一個程式碼區塊，並包含下列內容：

$ mkdir test
$ ls
test

然後，點選代碼塊上的複製按鈕，將只複製命令，而忽略提示和輸出。這可讓您指出它們是控制台指令，同時仍可讓使用者有效地使用複製按鈕。

強調特定的程式碼行

您可以高亮特定的程式碼行。例如，若要高亮第 2 行，您可以在語言後面加上一個空格，接著是 {hl_lines="2"}。因此，您的程式碼區塊會以 ``python {hl_lines="2"} 開頭。`.結果是

import toga
from toga.style.pack import COLUMN, ROW

您可以高亮顯示多個不同的行。例如，python {hl_lines="3 5 9"} 將會高亮第 3、5 和 9 行。您也可以高亮某一行。例如，python {hl_lines="3-8"} 會高亮顯示第 3 行至第 8 行。您可以高亮顯示多個範圍，例如，python {hl_lines="9-18 23-44"}。

需要特定格式的 Markdown 元素

由於翻譯檔案的產生方式，在 Markdown 語法中加入必要的換行線對於訓誡、註解、標籤、Jinja 指令、圖片標題和對齊方式等是很重要的。

訓誡和注意事項

訓誡的格式必須如下，包括確保在訓誡開始和結束之前和之後有一個換行符：

Content above.

/// admonition | Title

Admonition text.

A second paragraph.

///

Content below.

此機制對任何支援的警告類型皆適用。例如，註釋警告需遵循相同格式與換行規則：

Content above.

/// note | Note title

Note text here.

///

Content below.

所有 支援的告誡類型 皆可作為告誡使用。

標籤式內容

標籤內容的格式如下，包括在內容區塊的開始和結束之前包含一個換行符：

Content above.

/// tab | Tab one title

Tab one text

///

/// tab | Tab two title

Tab two text.

///

/// tab | Tab three title

Tab three text.

///

Content below.

具有巢狀訓誡的制表符格式如下，包括內容區塊前後的換行符：

Content above.

/// tab | Windows

Tab text.

/// admonition | Admonition

Admonition text.

///

///

Content below.

折疊內容

折疊內容的格式如下，包含換行符：

Content above.

/// details-note | Collapsed content title

Collapsed content.

///

Content below.

所有 支援的警示類型 皆可與折疊內容搭配使用，但必須以 details-admonitiontype 形式宣告。因此，「註解」類型的折疊區塊應為 details-note（如上所示），而「警告」類型的折疊區塊則為 details-warning，依此類推。

金賈指 令

文件中有一些功能在文字中使用了 Jinja 指令。任何使用 Jinja 指令功能的內容都需要用換行包裝。例如，BeeWare 教學包含基於變數的 Jinja 條件，以決定在主頁上顯示什麼訓誡。其格式如下：

Content above.



Content below.

也有替代符號或文字的語法。這種語法是以一對匹配的雙大括弧包覆變數，如果是在自己的行上，則必須在變數前後包含一個換行符。

Content above.

{{ variable }}

Content below.

圖片格式化

圖片可以設定寬度，並且可以向左、向右或居中對齊（「居中」需注意）。圖片應該包含有意義的 alt 文字，以利於存取。

在影像上設定寬度 300px 的格式如下：

![Image alt text](../path/to/image.png){ width="300px" }

向左（或向右）對齊影像的格式如下：

![Image alt text](../path/to/image.png){ align=left }

在影像上加入標題需要在前後加上換行，格式如下：

Content above.

![Image alt text](/path/to/image.png)

/// caption

Caption content.

///

Content below.

使用 align 屬性無法將圖片居中對齊。解決方法是在圖片後面加上空標題，這樣圖片就會居中對齊。您必須在每節之間以及前後加入換行符。其格式如下：

Content above.

![Image alt text](../path/to/image.png)

/// caption

///

Content below.

具有特定 Markdown 格式的外掛程式

以下各節將介紹如何利用需要特定 Markdown 格式的外掛程式。

使用片段包含外部內容

有關如何從本機檔案或 URL 包含外部內容的詳細資訊，請參閱 Snippets 延伸文件。只要文件不包含需要執行的Jinja指令，就應該使用Snippets（Jinja的執行會與Snippets的處理同時進行，因此文件中的任何Jinja都不會被處理）。Snippets 是必要的，如果您希望能夠使用分隔符，讓您可以分別包含檔案的特定部分，例如：將原始文件分割成不同的部分，彼此分開注入。

重要注意事項：

• 我們使用 -8<- 作為 Snippets 標識符。文件顯示了多種選項；請遵循我們的風格。
• 在 BeeWare Docs Tools 共用內容中找到的檔案被視為 「本地 」內容。因此，您可以只使用檔案名稱，如 -8<- "docs-style-guide.md「，或者如果內容在子目錄中，則只使用目錄和檔案名稱，如 -8<- 」style/docs-style-guide.md"。
• 如果您在 GitHub 上透過 URL 加入檔案中的外部內容，您 must 必須使用原始內容 URL，否則無論您在哪裡加入內容，都會呈現嵌入的完整網頁。

使用巨集從 BeeWare Docs Tools 共用內容中包含內容

您也可以使用 Macros MkDocs plugin 包含 BeeWare Docs tools 共享內容目錄中的內容。如果文件中包含需要執行的Jinja指令，則必須使用此方法，並且只能在這種情況下使用。對於透過 URL 取得的外部內容則無法使用。Macros 變數替代機制](https://mkdocs-macros-plugin.readthedocs.io/en/latest/pages/#1-variable)可與此方法一起使用。

有使用巨集包含內容的選項：

1. 如果您要包含文件而不對其進行其他手動變更，請使用 include金句語法。

2. 如果您在文件中包含了 Jinja block 語法，可以使用extends Jinja 語法，該語法允許您覆寫或添加到特定部分。

「拼寫」(pyspelling)

我們使用 pyspelling 拼字檢查器。它會在內部檢查時執行。

當 pyspelling 識別出拼寫錯誤的單字時，在大多數情況下，應該在文件內容中加以修正。

在罕見的情況下，如果它識別出一個不在 pyspelling 字典中的有效詞彙，您有兩個選擇：

1. 如果是一個可能會被多次重複使用的字，您應該將該字依字母順序加入docs目錄中的spelling_wordlist文件。
2. 如果是不太可能再使用的字，您可以用 <nospell> / </nospell> 標籤包住它，而 pyspelling 會在線上忽略它。