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"，在桌面端优先使用"the Obsidian application"。 - 优先使用"sync"或"syncing"而非"synchronise"或"synchronising"。 - 优先使用"search term"而非"search query"。 - 在指代引导某个章节的文本时，优先使用"heading"而非"header"。 - 优先使用"maximum"而非"max"，使用"minimum"而非"min"。 ### 产品名称 Obsidian 产品名称以"Obsidian"开头，例如"Obsidian Publish"和"Obsidian Sync"。 如果一个段落中重复过多，后续提及时可以使用简称。 例如： _为了允许设备特定的配置，Obsidian Sync 不会同步自身的设置。你需要为每台设备分别配置 Sync。_ ### 界面和交互 - 使用**加粗**来标示按钮文本 - 优先使用"选择"而非"点击"或"轻触"。 - 对于移动端特定的指令，由于不存在"点击"操作，在描述触摸交互时可以使用"轻触"。 - 优先使用"侧边栏"而非"侧 边 栏"。 - 在指代命令或操作时，优先使用"执行"而非"调用"。 在描述连续的多个界面操作时，使用 →（U+2192）符号。例如，"**[[设置]] → 社区插件**"。 ### 笔记、文件和文件夹 - 在指代仓库中的 Markdown 文件时使用"笔记"。 - 在指代 Markdown 以外的其他文件扩展名时使用"文件"。 - 优先使用"笔记名"而非"笔记标题"。 - 优先使用"当前笔记"而非"目前的笔记"。 - 优先使用"文件夹"而非"目录"。 - 优先使用"文件类型"而非"文件格式"，除非特别指代文件内容的数据格式。 在笔记之间切换时，如果目标笔记处于隐藏状态则使用"打开"，如果源笔记和目标笔记都在不同的分屏中打开则使用"切换"。 ### 设置的参考文档 尽可能在 Obsidian 内部通过描述性文本来记录设置。除非满足以下条件，否则避免在 Obsidian 帮助文档中记录特定设置： - 该设置需要更深入的知识来了解如何和何时使用。 - 该设置经常被误用或被频繁询问。 - 该设置会*显著*改变用户体验。 如果你想引起对特定设置的注意，可以考虑使用提示标注。 ### 方向性用词 当方向性词语用作形容词时使用连字符。当方向用作名词时避免使用连字符。 **推荐：** - 选择左下角的**[[设置]]**。 - 选择左下方的**[[设置]]**。 **不推荐：** - 选择左下角的**[[设置]]**。（缺少连字符的形容词用法） - 选择左下方的**[[设置]]**。（多余连字符的名词用法） 优先使用"左上角"和"右上角"而非"顶部左侧"和"顶部右侧"。 在指代设置时不要标示方向。设置控件的位置取决于设备。 **推荐：** - 在**选择远程仓库**旁边，选择**选择**。 **不推荐：** - 在**选择远程仓库**的右侧，选择**选择**。 在描述界面元素的垂直方向时，使用"上方"和"下方"来表示空间关系。避免使用"上面"和"下面"，因为它们在不同语境中可能产生歧义。 **推荐：** - 搜索框出现在文件列表上方。 - 更多选项在下方可用。 **不推荐：** - 搜索框在文件列表上面。 - 更多选项在下面。 ### 操作指引 在指南名称、章节标题和分步指引中使用祈使句。祈使语气简洁且以行动为导向，对于遵循指引的用户来说更加直观。 - 优先使用"设置"而非"设置中" - 优先使用"移动文件"而非"移动文件的方法" - 优先使用"导入你的笔记"而非"导入笔记的步骤" ### 大小写规则 标题、按钮和标题文本优先使用*句首大写*而非*每词首字母大写*。在引用界面元素时，始终与界面中的文本大小写保持一致。 **推荐：** - 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. 第三项 ``` **列表中的破折号：** 在无序列表中，使用破折号（——）将加粗的术语与其描述分隔开。在包含链接的简单嵌套无序列表中不要使用破折号。 **推荐：** - **视图菜单** —— 创建、编辑和切换视图。 - **计算数值** —— 添加价格、计算总计或执行数学运算。 **不推荐：** - [[创建 Base]] —— 了解如何创建和嵌入数据库。 ### 图片 使用"**宽度** x **高度** 像素"来描述图片或屏幕尺寸。 **示例：** 推荐的图片尺寸：1920 x 1080 像素。 ## 信息结构 ### 标注类型 有策略地使用标注来突出显示特定类型的信息： **提示** (`[!tip]-`) - 增强用户工作流程的实用建议或最佳实践。用于快捷方式、变通方法或非必要但有帮助的信息。此类标注默认折叠。 **信息** (`[!info]+`) - 附加的上下文、背景信息或澄清说明。当信息有助于理解但并非完成任务所必需时使用。此类标注默认展开。 **警告** (`[!warning]+`) - 防止数据丢失、错误或意外后果的重要提醒。仅在确实存在风险的情况下谨慎使用。此类标注不应折叠。 **示例** (`[!example]-`) - 一般性的补充说明或附加细节。用于某些用户可能觉得相关的附带信息。此类标注默认折叠。 **示例：** ```md > [!tip]- 使用快捷键 > 你可以通过记住最常用的快捷键来加快工作流程。 > [!info]+ 这是一个付费附加功能 > 此功能需要付费订阅才能使用。 > [!warning]+ 此操作无法撤销 > 删除仓库是永久性的。请先考虑导出你的笔记。 > [!example]- 高级用法 > 你也可以通过关系图谱菜单来配置此设置。 ``` ### 列表与段落 当展示没有强烈顺序或因果关系的离散项目时，使用列表。当各项之间相互关联、需要解释或适合叙述性表达时，使用段落。 **适合使用列表的场景：** - 一组不相关的功能 - 安装要求 - 配置选项 - 故障排查步骤 **适合使用段落的场景：** - 解释某事物的工作原理 - 具有依赖关系的工作流程 - 概念概述 - 需要上下文的指导说明 ### 表格 使用表格来比较功能、版本或相关数据点，以便对齐展示有助于理解。避免将表格用于简单列表或单列数据。 **适合使用表格的场景：** | 功能 | 移动端 | 桌面端 | |---------|--------|---------| | 同步 | 是 | 是 | | 插件 | 否 | 是 | | 主题 | 有限 | 完整 | ### 交叉引用 充分使用内部 Wiki 链接（`[[笔记名]]`）来帮助用户导航相关主题。但要避免过度链接： - 不要在同一页面中多次链接相同的术语 - 仅在被引用的页面提供重要补充信息时才进行链接 - 在有帮助时使用描述性链接文本：`[[笔记名#章节|描述性文本]]` **示例：** 首次提及："了解 [[Obsidian 官方同步简介|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] 实时预览警告 > 图标锚点标签在**实时预览**中无法正确显示。请使用**阅读视图**确认锚点标签已正确应用。 **Icon** `![[lucide-menu.svg#icon]]` icon 锚点标签确保用于表示界面元素的图标具有正确的垂直对齐。 第一个菜单图标使用了锚点标签（ ![[lucide-menu.svg#icon]] ），而第二个菜单图标（ ![[lucide-menu.svg]] ）没有使用。 **Interface** `![[Vault picker.png#interface]]` interface 锚点标签在图片周围添加装饰性阴影。在第一张图片中，应用了 interface 锚点标签。 ![[Vault picker.png#interface]] 相比之下，第二张图片没有应用 interface 锚点。 ![[Vault picker.png]] **Outline** `![[Backlinks.png#outline]]` outline 锚点标签在图片周围添加一个微妙的边框。在第一张图片中，应用了 outline 锚点标签。 > [!tip] 观察图片的左下角以查看差异。 ![[Backlinks.png#outline]] 第二张图片没有使用 outline 锚点标签。 ![[Backlinks.png]] ### 优化 图片会减慢页面加载速度，并占用宝贵的 [[发布服务简介|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]] 在线托管，其中包含用于社交卡片和其他 [[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 时说明这一点。 ## 翻译 完成翻译时，请翻译全部内容。这包括但不限于： - 笔记名称 - 文件夹名称 - 别名 - 附件名称 - 替代链接文本