Obsidian 兼容
约 1698 字大约 6 分钟
2026-04-17
概述
主题通过 vuepress-plugin-md-power 插件提供对 Obsidian 官方 Markdown 扩展语法的兼容性支持,使 Obsidian 用户能够以熟悉的语法撰写文档。
当前已支持的 Obsidian 扩展语法包括:
不计划支持 Obsidian 社区第三方插件提供的扩展语法
配置
Obsidian 兼容功能默认全部启用,你可以通过配置选择性地启用或禁用:
export default defineUserConfig({
theme: plumeTheme({
plugins: {
mdPower: {
obsidian: {
wikiLink: true, // Wiki 链接
embedLink: true, // 嵌入内容
callout: true, // Callout
comment: true, // 注释
},
pdf: true, // PDF 嵌入功能
artPlayer: true, // 视频嵌入功能
}
}
})
})配置项
Wiki 链接
Wiki 链接是 Obsidian 中用于链接到其他笔记的语法。使用双括号 [[]] 包裹内容来创建内部链接。
语法
[[文件名]]
[[文件名#标题]]
[[文件名#标题#子标题]]
[[文件名|别名]]
[[文件名#标题|别名]]
[[https://example.com|外部链接]]文件名搜索规则
当使用 Wiki 链接时,文件名会按照以下规则进行搜索匹配:
匹配优先级:
- 完整路径 - 精确匹配文件路径
- 模糊匹配 - 匹配路径结尾的文件名,优先匹配最短路径
路径解析规则:
- 相对路径(以
.开头):相对于当前文件所在目录解析 - 绝对路径(不以
.开头):在整个文档树中搜索,优先匹配最短路径 - 目录形式(以
/结尾):匹配该目录下的README.md
示例:
假设文档结构如下:
docs/
├── README.md
├── guide/
│ ├── README.md
│ └── markdown/
│ └── obsidian.md在 docs/guide/markdown/obsidian.md 中:
| 语法 | 匹配结果 |
|---|---|
[[obsidian]] | 匹配 docs/guide/markdown/obsidian.md(通过文件名检索) |
[[./]] | 匹配 docs/guide/markdown/README.md(相对路径) |
[[../]] | 匹配 docs/guide/README.md(上级目录) |
[[guide/]] | 匹配 docs/guide/README.md(目录形式) |
示例
外部链接:
输入:
[[https://example.com|外部链接]]输出:
内部锚点链接:
输入:
[[npm-to]] <!-- 通过文件名检索 -->
[[guide/markdown/math]] <!-- 通过文件路径检索-->
[[#Wiki 链接]] <!-- 当前页面使用 heading -->
[[file-tree#配置]] <!-- 通过文件名检索,并链接到 heading -->输出:
嵌入内容
嵌入语法允许你将其他文件资源插入到当前页面中。
语法
![[文件名]]
![[文件名#标题]]
![[文件名#标题#子标题]]文件名搜索规则与 Wiki 链接 相同。
以 / 开头或 无路径前缀如 ./ 形式的,从 public 目录中加载资源
图片嵌入
语法:
![[图片]]
![[图片|宽度]]
![[图片|宽度x高度]]支持格式:jpg、jpeg、png、gif、avif、webp、svg、bmp、ico、tiff、apng、jfif、pjpeg、pjp、xbm
示例:

基础图片
![[images/custom-hero.jpg]]
设置宽度
![[images/custom-hero.jpg|300]]
设置宽度和高度
![[images/custom-hero.jpg|300x200]]PDF 嵌入
笔记
PDF 嵌入需要启用 markdown.pdf 插件才能正常工作。
语法:
![[文档.pdf]]
![[文档.pdf#page=1]] <!-- #page=1 表示第一页 -->
![[文档.pdf#page=1#height=300]] <!-- #page=页码 #height=高度 -->支持格式:pdf
音频嵌入
语法:
![[音频文件]]支持格式:mp3、flac、wav、ogg、opus、webm、acc
视频嵌入
笔记
视频嵌入需要启用 markdown.artPlayer 插件才能正常工作。
语法:
![[视频文件]]
![[视频文件#height=400]] <!-- 设置视频高度 -->支持格式:mp4、webm、mov 等
内容片段嵌入
通过 #标题 可以嵌入指定标题下的内容片段:
输入:
![[我的笔记]]
![[我的笔记#标题一]]
![[我的笔记#标题一#子标题]]Obsidian 官方 - 插入文件Obsidian 官方 - 文件格式
Callout
Callout 是一种用于突出显示重要信息的语法,类似于 VuePress 的 ::: hint 提示框语法。
语法
> [!note]
> 内容可选标题:
> [!tip] 自定义标题
> 内容类型
Callout 支持以下类型,别名会自动映射到对应的主要类型:
| 类型 | 别名 | 说明 |
|---|---|---|
note | quote, cite | 笔记、引用 |
tip | hint | 技巧、提示 |
info | todo | 信息、待办 |
success | check, done | 成功、完成 |
warning | question, help, faq | 警告、问题、帮助 |
caution | attention, failure, fail, missing, danger, error, bug | 注意、失败、危险 |
important | example | 重要、示例 |
details | abstract, summary, tldr | 详情、摘要 |
示例
基础用法:
输入:
> [!NOTE]
> 这是一个笔记提示框。输出:
笔记
这是一个笔记提示框。
带标题:
输入:
> [!TIP] 实用技巧
> 使用 `pnpm` 可以显著加快依赖安装速度。输出:
实用技巧
使用 pnpm 可以显著加快依赖安装速度。
多种类型:
输入:
> [!success]
> 操作成功完成!
>
> [!warning]
> 这是一个警告信息。
>
> [!caution]
> 请谨慎操作,此操作不可撤销。输出:
成功
操作成功完成!
警告
这是一个警告信息。
注意
请谨慎操作,此操作不可撤销。
Details 类型:
details 类型会渲染为 HTML <details> 元素,支持折叠展开:
输入:
> [!details]
> 点我展开更多内容
>
> 这是一段隐藏的内容。输出:
详情
点我展开更多内容
这是一段隐藏的内容。
注释
使用 %% 包裹的内容会被当作注释,不会渲染到页面中。
语法
行内注释:
这是一个 %%行内注释%% 示例。块级注释:
%%
这是一个块级注释。
可以跨越多行。
%%示例
行内注释:
输入:
这是一个 %%行内注释%% 示例。输出:
这是一个 示例。
块级注释:
输入:
注释之前的内容
%%
这是一个块级注释。
可以跨越多行。
%%
注释之后的内容输出:
注释之前的内容
可以跨越多行。
注意事项
- 这些插件提供的是 兼容性支持,并非完全实现 Obsidian 的全部功能
- 部分 Obsidian 特有的功能(如内部链接的图谱视图、双向链接等)不在支持范围内
- 嵌入内容时,被嵌入的页面也会参与主题的构建过程
- PDF 嵌入需要同时启用
markdown.pdf插件 - 视频嵌入需要同时启用
markdown.artPlayer插件 - 以
/开头或使用./形式的嵌入资源会从public目录加载
