Obsidian 文件遵循本頁列出的樣式指南。這些指南基於業界最佳實踐，特別是 [Google 開發者文件樣式指南](<https://developers.google.com/style>) 和 [Microsoft 樣式指南](https://learn.microsoft.com/en-us/style-guide/)。對於以下未涵蓋的邊緣情況，請參考上述外部指南作為輔助參考。 > [!tip]- 貢獻 > 大多數文件在本樣式指南制定之前就已存在。 > > 如果你發現任何違反本樣式指南的內容，請[建立 issue](https://github.com/obsidianmd/obsidian-docs/issues/new) 並向 [obsidianmd/obsidian-docs](https://github.com/obsidianmd/obsidian-docs) 提交 pull request。 ## 術語與文法 ### 語言風格 對於英文文件，建議使用[全球英文](https://docs.openedx.org/en/latest/documentors/references/doc_english_writing.html)以更好地服務全球讀者，並協助[[#翻譯]]工作。這意味著： - 避免使用慣用語和特定文化的表達方式 - 使用主動語態和直接的句子結構 - 優先使用簡單、常見的詞彙，而非複雜的術語 - 明確表達而非隱含暗示 - 拼寫慣例方面，使用美式英文（例如 'organize' 而非 'organise'）。 ### 用語 - 優先使用「keyboard shortcut」（鍵盤快捷鍵）而非「hotkey」。當指稱特定功能時才使用 Hotkey。 - 在行動裝置上優先使用「the Obsidian app」（Obsidian 應用程式），在桌面版優先使用「the Obsidian application」（Obsidian 應用程式）。 - 優先使用「sync」或「syncing」而非「synchronise」或「synchronising」。 - 優先使用「search term」（搜尋詞）而非「search query」。 - 當指稱引導章節的文字時，優先使用「heading」（標題）而非「header」。 - 優先使用「maximum」而非「max」，「minimum」而非「min」。 ### 產品名稱 Obsidian 產品名稱以「Obsidian」開頭，例如「Obsidian Publish」和「Obsidian Sync」。 如果段落變得過於重複，可以在後續引用中使用簡稱。 例如： _為了允許裝置特定的設定，Obsidian Sync 不會同步自身的設定。你需要為每個裝置分別設定 Sync。_ ### 使用者介面與互動 - 使用**粗體**表示按鈕文字 - 優先使用「選取」而非「點擊」或「按一下」。 - 對於行動裝置的專屬說明，在描述觸控操作時可以使用「輕觸」，因為「點擊」不適用。 - 優先使用「側邊欄」而非「側邊列」。 - 當指稱命令或操作時，優先使用「執行」而非「調用」或「運行」。 當指稱一連串的 UI 互動時，使用 →（U+2192）符號。例如「**[[設定]] → 社群外掛程式**」。 ### 筆記、檔案和資料夾 - 當指稱保管庫中的 Markdown 檔案時，使用「筆記」。 - 當指稱 Markdown 以外的其他副檔名檔案時，使用「檔案」。 - 優先使用「筆記名稱」而非「筆記標題」。 - 優先使用「目前筆記」而非「當前筆記」。 - 優先使用「資料夾」而非「目錄」。 - 優先使用「檔案類型」而非「檔案格式」，除非特別指稱檔案內容的資料格式。 在筆記之間移動時，如果目標筆記處於隱藏狀態，使用「開啟」；如果來源和目標筆記都已在不同的分割視窗中開啟，則使用「切換」。 ### 設定的參考文件 盡可能在 Obsidian 內部使用描述性文字來記錄設定。除非以下情況，否則避免在 Obsidian 說明中記錄特定設定： - 需要更深入了解如何及何時使用該設定。 - 該設定經常被誤用或被詢問。 - 該設定會_大幅_改變使用者體驗。 如果你想引起使用者對特定設定的注意，考慮使用提示標註塊。 ### 方位用語 當方位用語作為形容詞時，使用連字號。當方位作為名詞使用時，避免使用連字號。 **建議：** - 選取左下角的**[[設定]]**。 - 選取左下方的**[[設定]]**。 **不建議：** - 選取左下角 的**[[設定]]**。 - 選取左下方的**[[設定]]**。 優先使用「左上角」和「右上角」而非「上左方」和「上右方」。 指稱設定時不要標示方位。設定控制項的位置取決於裝置。 **建議：** - 在**選擇遠端庫**旁邊，選取**選擇**。 **不建議：** - 在**選擇遠端庫**的右側，選取**選擇**。 描述 UI 元素的垂直方向時，使用「上方」和「下方」表示空間關係。避免使用「往上」和「往下」，因為它們在不同情境下可能會造成歧義。 **建議：** - 搜尋框會出現在檔案清單上方。 - 更多選項在下方。 **不建議：** - 搜尋框在檔案清單的上面。 - 更多選項在下面。 ### 操作說明 指南名稱、章節標題和步驟說明請使用祈使句。祈使語氣簡潔且以行動為導向，對於遵循操作說明的使用者來說更為直接。 - 優先使用「設定」而非「正在設定」 - 優先使用「搬移檔案」而非「搬移檔案中」 - 優先使用「匯入你的筆記」而非「正在匯入你的筆記」 ### 大小寫 標題、按鈕和標題文字優先使用*句首大寫*而非*標題大寫*。引用 UI 元素時，請始終與 UI 中的文字大小寫保持一致。 **建議：** - How Obsidian stores data **不建議：** - How Obsidian Stores Data ### 範例 優先使用實際的範例而非無意義的詞彙。 **建議：** - `task:(call OR schedule)` **不建議：** - `task:(foo OR bar)` ### 按鍵名稱與鍵盤快捷鍵 指稱鍵盤按鍵和快捷鍵時，使用一致的標記方式。 **單獨的按鍵名稱：** 以名稱指稱鍵盤上的字元時，在名稱後面加上括號標示該字元。 **建議：** - 按下連字號（-）鍵來新增一個破折號。 - 使用問號（?）來搜尋。 **不建議：** - 按下連字號鍵來新增一個破折號。 - 使用 ? 來搜尋。 - 在字詞前面加上 `-`。 **鍵盤快捷鍵：** 鍵盤快捷鍵格式中加號前後不加空格。當快捷鍵在不同作業系統之間有所不同時，請同時標明兩者。 **建議：** - 按下 `Ctrl+Z`（Windows）或 `Command+Z`（macOS）來復原。 - 按下 `Escape` 關閉此視窗。 - 使用 `Tab` 在欄位之間移動。 **不建議：** - 按下 `Cmd+Z` 來復原。 - 按下 `Ctrl + Z`（有空格）來復原。 - 按下 `Ctrl/Cmd+Z` 來復原。 對於在所有平台上都相同的快捷鍵，不需要標明作業系統。如果你不確定快捷鍵是否因平台而異，為安全起見請標明作業系統。Windows 和 Linux 通常使用相同的快捷鍵。 ### Markdown 在 Markdown 區塊之間使用空行： **建議：** ```md # 標題 1 這是一個章節。 1. 第一項 2. 第二項 3. 第三項 ``` **不建議：** ```md # 標題 1 這是一個章節。 1. 第一項 2. 第二項 3. 第三項 ``` **清單中的破折號：** 在項目符號清單中，使用破折號（—）來分隔粗體的術語和其描述。在只有連結的簡單巢狀項目符號清單中，不要使用破折號。 **建議：** - **檢視選單** — 建立、編輯和切換檢視。 - **計算數值** — 新增價格、計算總額或執行數學運算。 **不建議：** - [[建立資料庫]] — 了解如何建立和嵌入資料庫。 ### 圖片 使用「**寬度** x **高度** 像素」描述圖片或螢幕尺寸。 **範例：** 建議的圖片尺寸：1920 x 1080 像素。 ## 資訊結構 ### 標註塊類型 策略性地使用標註塊來強調特定類型的資訊： **提示**（`[!tip]-`）— 增強使用者工作流程的實用建議或最佳實踐。用於快捷方式、替代方案或非必要但有幫助的資訊。這些標註塊預設為摺疊狀態。 **資訊**（`[!info]+`）— 額外的上下文、背景資訊或說明。當資訊有助於理解但不是完成任務所必需時使用。這些標註塊預設為展開狀態。 **警告**（`[!warning]+`）— 防止資料遺失、錯誤或意外後果的重要注意事項。僅在確實有風險的情況下謹慎使用。這些標註塊不應被摺疊。 **範例**（`[!example]-`）— 一般性的附註或補充細節。用於某些使用者可能覺得相關的延伸資訊。這些標註塊預設為摺疊狀態。 **範例：** ```md > [!tip]- 使用鍵盤快捷鍵 > 你可以透過記憶最常用的快捷鍵來加速你的工作流程。 > [!info]+ 這是付費附加功能 > 此功能需要付費訂閱才能使用。 > [!warning]+ 此操作無法復原 > 刪除保管庫是永久性的。請考慮先匯出你的筆記。 > [!example]- 進階用法 > 你也可以透過圖譜選單來設定此選項。 ``` ### 清單與段落文字 當呈現獨立且彼此之間沒有強烈順序或因果關係的項目時，使用清單。當項目之間有關聯、需要解釋，或適合以敘事方式呈現時，使用段落文字。 **以下情況使用清單：** - 一組不相關的功能 - 安裝需求 - 設定選項 - 疑難排解步驟 **以下情況使用段落文字：** - 解釋某功能如何運作 - 具有依賴關係的工作流程 - 概念性概述 - 需要上下文的指導 ### 表格 使用表格來比較功能、版本或相關資料點，當對齊方式有助於理解時特別適用。避免將表格用於簡單的清單或單欄資料。 **良好的使用場景：** | 功能 | 行動裝置 | 桌面版 | |---------|--------|---------| | 同步 | 是 | 是 | | 外掛 | 否 | 是 | | 主題 | 有限 | 完整 | ### 交叉引用 大量使用內部 Wiki 連結（`[[筆記名稱]]`）來幫助使用者導覽相關主題。但是，避免過度連結： - 不要在同一頁面中多次連結相同的術語 - 僅在被引用的頁面能提供顯著的額外上下文時才建立連結 - 需要時使用描述性的連結文字：`[[筆記名稱#章節|描述性文字]]` **範例：** 首次提及：「了解 [[Obsidian Sync 簡介|Obsidian Sync]]，讓你的保管庫在不同裝置間保持同步。」 後續提及：「你可以為每個裝置分別設定 Sync。」 ### 平台特定內容 當記錄不同平台之間有差異的功能時，使用章節標題來組織內容。 使用 `桌面版` 和 `行動裝置` 作為小節標題來區分平台特定的說明或功能。 **建議：** ```md ## 自訂功能區 ### 桌面版 在桌面版中，你可以透過以下方式自訂功能區： - 拖放圖示來重新排列功能區操作的順序。 - 要隱藏特定操作，在空白處按右鍵並取消勾選你想隱藏的操作。 ### 行動裝置 在行動版中，你可以透過設定來自訂功能區： 1. 開啟**[[設定]]**。 2. 導覽至**外觀**。 3. 在**功能區設定**下方點選**管理**。 ``` > [!info]+ 何時需要建立獨立章節？ > 僅在內容有顯著差異時才建立獨立章節。如果說明大致相同只有些微差異，請改用行內備註。 ## 圖示與圖片 當圖示和圖片能讓難以用文字描述的事物更容易說明，或當你需要展示 Obsidian 應用程式的重要部分時，請加入圖示和圖片。你可以將圖片儲存在 `Attachments` 資料夾中。 - 圖片應讓其所附帶的文字更容易理解。 **範例**：啟用後，[[字數統計]]外掛會在底部狀態列中建立一個新的項目。 ![[Style-guide-zoomed-example.png#interface|300]] - 圖片應為 `.png` 或 `.svg` 格式。 - 如果圖片在筆記中看起來太大，請在 Obsidian 外部縮小圖片，或按照[[嵌入檔案#在筆記中嵌入圖片|在筆記中嵌入圖片]]中說明的方式調整其尺寸。 - 在少數情況下，你可能需要將特別大或複雜的圖片放在[[註標#可摺疊標註塊|可摺疊標註塊]]中。 - 對於彈出視窗或對話框，圖片應顯示整個 Obsidian 應用程式視窗。 ![[Style-guide-modal-example.png#interface]] ### 圖示 [Lucide](https://lucide.dev/icons/) 和自訂 Obsidian 圖示可以與詳細元素一起使用，提供功能的視覺呈現。 **範例：** 在左側功能區中，選取**建立新畫布** ![[lucide-layout-dashboard.svg#icon]] 以在與目前筆記相同的資料夾中建立一個白板。 **圖示使用指南** - 將圖示儲存在 `Attachments/icons` 資料夾中。 - 在 Lucide 圖示名稱前加上 `lucide-` 前綴。 - 在 Obsidian 圖示名稱前加上 `obsidian-icon-` 前綴。 **範例：** 建立新畫布的圖示應命名為 `lucide-layout-dashboard`。 - 使用可用的 SVG 版本圖示。 - 圖示寬度應為 `18` 像素，高度為 `18` 像素，線條寬度為 `1.5`。你可以在 SVG 資料中調整這些設定。 > [!info]- 在 SVG 中調整尺寸和線條寬度 > ```html > <svg xmlns="http://www.w3.org/2000/svg" width="WIDTH" height="HEIGHT" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="STROKE-WIDTH" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-layout-dashboard"><rect width="7" height="9" x="3" y="3" rx="1"/><rect width="7" height="5" x="14" y="3" rx="1"/><rect width="7" height="9" x="14" y="12" rx="1"/><rect width="7" height="5" x="3" y="16" rx="1"/></svg> >``` - 在嵌入圖片中使用 `icon` 錨點，以調整圖示周圍的間距，使其與附近的文字整齊對齊。 - 圖示應被括號包圍。![[lucide-cog.svg#icon]] **範例**：`![[lucide-cog.svg#icon]]` ### 圖片錨點標籤 圖片錨點標籤可用於為嵌入的圖片添加裝飾性變更。 > [!warning] 即時預覽警告 > 圖示錨點標籤在**即時預覽**中無法正確顯示。請使用**閱讀檢視**來確認錨點標籤已正確套用。 **圖示** `![[lucide-menu.svg#icon]]` 圖示錨點標籤可確保用於表示介面元素的圖示有正確的垂直對齊。 第一個選單圖示使用了錨點標籤 ![[lucide-menu.svg#icon]]，而第二個選單圖示（![[lucide-menu.svg]]）則沒有。 **介面** `![[Vault picker.png#interface]]` 介面錨點標籤會在圖片周圍添加裝飾性的陰影效果。在第一張圖片中，已套用介面錨點標籤。 ![[Vault picker.png#interface]] 相比之下，第二張圖片沒有套用介面錨點。 ![[Vault picker.png]] **外框** `![[Backlinks.png#outline]]` 外框錨點標籤會在圖片周圍添加細微的邊框。在第一張圖片中，已套用外框錨點標籤。 > [!tip] 觀察圖片的左下角來查看差異。 ![[Backlinks.png#outline]] 第二張圖片沒有外框錨點標籤。 ![[Backlinks.png]] ### 最佳化 圖片會拖慢頁面的載入時間，並佔用寶貴的 [[Obsidian Publish 介紹|Publish]] 儲存空間。最佳化圖片可以減少檔案大小，同時維持圖片的視覺品質。 圖片和圖示都應該進行最佳化。 > [!info] 圖片最佳化工具 > 以下是一些推薦的縮減圖片大小的程式。 > - **Windows：** [FileOptimizer](https://sourceforge.net/projects/nikkhokkho/) > - **macOS：** [ImageOptim](https://imageoptim.com/) > - **Linux/Unix：** [Trimage](https://trimage.org) > > 我們建議最佳化率為 65-75%。 ## 版面配置 ### 失效連結 在提交 Pull Request 之前，請檢查你正在翻譯的文件中是否有失效的連結，並加以修正。失效連結可能隨著時間自然產生，因此驗證其正確性有助於維護文件品質。 你可以使用[[社群外掛程式]]或 IDE 中可用的工具來檢查失效連結。 ### 描述 本文件在 GitHub 上編輯，並透過 [[Obsidian Publish 介紹|Obsidian Publish]] 在線上發佈，其中包含用於社群卡片的[[社群媒體連結預覽#描述|描述]]和其他 [[SEO]] 元素。 如果你正在處理的頁面沒有 `description` [[屬性|屬性]]，請新增一個。描述應在 150 個字元以內，並提供頁面內容的客觀摘要。 **良好**：Learn to create templates that capture and organize web page metadata automatically with Web Clipper. **可以改進**：Learn how to create templates that automatically capture and organize metadata from web pages with Web Clipper. ### 操作方向 在撰寫或改寫如何在應用程式中執行操作的[[#操作說明]]時，請務必包含行動裝置和桌面版的步驟。 如果你無法使用行動裝置或桌面裝置，請在提交 Pull Request 時提及此事。 ## 翻譯 完成翻譯時，請翻譯所有內容。這包括但不限於： - 筆記名稱 - 資料夾名稱 - 別名 - 附件名稱 - 替代連結文字