Obsidian Writer

编写能在 Obsidian 中正确渲染的 .md 和 .canvas 文件。输出到通过 Git 同步的 vault 目录。

Vault 位置

默认：~/obsidian-vault/（可根据请求配置）。

工作流程

1. 1. 按照以下规范编写 .md / .canvas 文件
2. Git 提交 + 推送（代理自动执行）
3. 用户的 Mac Mini 拉取 → 同步到 iCloud → Obsidian 读取

Markdown — Obsidian 特有语法

标准 Markdown（标题、加粗、列表、代码块）视为已知。仅以下 Obsidian 扩展：

属性（Frontmatter）

必须是文件中的最开头内容：

yaml

---

tags:
- finance/macro
- iran-war
aliases:
- 伊朗战争概览
cssclasses:
- wide-page
created: 2026-03-10

---

保留键：tags、aliases、cssclasses、publish、permalink、description。

内部链接（Wikilinks）

markdown
[[笔记名称]] # 链接到笔记
[[笔记名称|显示文本]] # 自定义显示
[[笔记名称#标题]] # 链接到标题
[[笔记名称^块ID]] # 链接到块

块引用

在任何段落/列表项末尾添加 ^块ID：

markdown
这是一个重要的段落。^关键见解

• - 列表项 ^项目引用

然后链接：[[笔记名称#^关键见解]]

块 ID：仅限小写字母数字和短横线。

嵌入

markdown
![[笔记名称]] # 嵌入整个笔记
![[笔记名称#标题]] # 嵌入章节
![[image.png]] # 嵌入图片
![[image.png|300]] # 调整宽度为300px
![[image.png|300x200]] # 精确尺寸
![[audio.mp3]] # 嵌入音频播放器
![[video.mp4]] # 嵌入视频播放器
![[document.pdf]] # 嵌入PDF
![[document.pdf#page=3]] # 嵌入特定页面

支持的格式 — 参见 references/file-formats.md。

标注框

markdown

[!note] 可选标题

包含 Markdown 和 [[wikilinks]] 的内容。

[!tip]- 可折叠（默认折叠）
隐藏的内容。

[!warning]+ 可折叠（默认展开）
显示的内容。

13 种类型：note、abstract/summary/tldr、info、todo、tip/hint/important、success/check/done、question/help/faq、warning/caution/attention、failure/fail/missing、danger/error、bug、example、quote/cite。

其他 Obsidian 扩展

markdown
==高亮文本== # 高亮
%%隐藏注释%% # 不渲染

• - [ ] 未完成任务 # 任务
• [x] 已完成任务 # 已完成任务

$E = mc^2$ # 行内 LaTeX
$$\int_0^\infty f(x)dx$$ # 块级 LaTeX
这是一个脚注[^1]。 # 脚注
[^1]: 脚注内容。

标签

markdown
#标签 # 简单标签
#父级/子级 # 嵌套标签

标签位于正文或 frontmatter 中。不允许有空格。

Mermaid 图表

markdown
mermaid
graph TD
A[开始] --> B{决策}
B -->|是| C[行动]
B -->|否| D[结束]

Canvas — JSON Canvas 规范 1.0

完整规范：references/canvas-spec.md

快速参考

json
{
nodes: [
{
id: node1,
type: text,
x: 0, y: 0,
width: 400, height: 200,
text: # 标题\n\nMarkdown 内容,
color: 4
},
{
id: node2,
type: file,
x: 500, y: 0,
width: 400, height: 400,
file: path/to/note.md,
subpath: #heading
},
{
id: node3,
type: link,
x: 0, y: 300,
width: 400, height: 300,
url: https://example.com
},
{
id: group1,
type: group,
x: -50, y: -50,
width: 1000, height: 500,
label: 组名称,
color: 5
}
],
edges: [
{
id: edge1,
fromNode: node1,
fromSide: right,
toNode: node2,
toSide: left,
color: 1,
label: 关联于
}
]
}

节点类型：text、file、link、group。
颜色：1 红色、2 橙色、3 黄色、4 绿色、5 青色、6 紫色，或十六进制 #FF0000。
边端点：fromEnd/toEnd → none 或 arrow（toEnd 默认为 arrow）。
方向：top、right、bottom、left。

Canvas 布局提示

• - 使用网格：节点位置为 50px 的倍数
• 标准节点：400×200（文本）、400×400（文件/链接）
• 组：包含节点周围 50px 内边距
• 节点数组顺序 = z-index（最后 = 最上层）

文件命名

kebab-case.md # 笔记文件
YYYY-MM-DD-title.md # 每日/日期笔记
kebab-case.canvas # canvas 文件

文件名中无空格、无特殊字符、无中日韩文字（为了 Git 跨平台安全）。

Vault 结构

vault/
├── 00-inbox/ # 新/未分类笔记
├── 01-projects/ # 活跃项目
├── 02-areas/ # 持续领域
├── 03-resources/ # 参考资料
├── 04-archive/ # 归档笔记
├── assets/ # 图片、PDF、附件
├── canvas/ # .canvas 文件
├── templates/ # 笔记模板
└── .gitignore

.gitignore

gitignore
.obsidian/workspace.json
.obsidian/workspace-mobile.json
.obsidian/app.json
.trash/
.DS_Store
.smart-connections/

保留 .obsidian/ 的跟踪（排除易变文件），以便插件/主题同步。

安全护栏

• - 绝不修改 .obsidian/ 配置文件
• 内部链接始终使用 [[wikilinks]]，而非 text
• UTF-8 编码，LF 换行符
• 附件路径相对于 vault 根目录
• 写入前验证 canvas JSON 的有效性