English | 中文
Vsidian 在 VSCode 里提供接近 Obsidian 的 Markdown 编辑体验。安装后打开 .md 文件直接进入实时预览：文档以渲染后的样子呈现，光标移到标题、链接或公式上时显示对应源码，改完即恢复渲染；也可以切换到纯阅读模式，或随时回到原生源码编辑器。
- 实时预览与阅读都只渲染视口内的内容：大型文档的滚动与编辑性能不随文件变大而下降。
- 类 Obsidian 的编辑习惯：双链与块引用跳转、悬停预览与文档嵌入（嵌入内可直接编辑）、反链与出链面板、更名文件自动更新引用、表格网格编辑、任务勾选、frontmatter 属性表、粘贴图片自动落盘、标题章节折叠、正文统一右键菜单（表格、图形块与链接另有专属操作），常用操作都在熟悉的位置。
- 样式入口公开：内置 CSS 片段体系，公开样式契约在设置页离线查阅并可导出 JSON，Obsidian 原名选择器与 CSS 变量直接兼容。
扩展市场（推荐）：VSCode（1.82+）扩展面板搜索 Vsidian，或打开 Marketplace 页面，安装后重启。
VSIX 手动安装：从 GitHub Releases 下载 vsidian-*.vsix，命令面板 →「Extensions: Install from VSIX…」选择该文件并重启。Remote SSH 场景在远端扩展目录安装同一 VSIX。
| 功能 |
说明 |
| 三态视图 |
实时预览、阅读、源码编辑器三态切换，最近模式与滚动位置跨窗口记住 |
| 默认编辑器守护 |
其他扩展抢占 .md 默认编辑器时主动提示并支持一键改回；设置页「常规」组实时显示当前默认编辑器 |
| 统一右键菜单 |
实时预览正文右键弹出链接、格式、剪贴板三簇菜单，含级联子菜单、图标与快捷键提示 |
| 文本格式 |
命令面板与快速操作条覆盖粗体、斜体、高亮、标题六级、行内代码等，全部可绑定快捷键 |
| 标题折叠 |
悬停标题行点击箭头收起该节正文（折叠后显示 ⋯ 占位）；五条折叠操作可绑定快捷键，折叠状态跨撤销、外部修改与双视图切换保持 |
| 富文本 / 纯文本粘贴 |
Ctrl+V 将可表达格式转为 Markdown，默认询问并分步撤销；Ctrl+Shift+V 保留原始文字与 Markdown 标记；详见 粘贴说明 |
| 多光标编辑 |
Alt+点击与 Ctrl+Alt+Up/Down 添加光标，多选区并行键入与格式操作，Esc 收敛回单光标（设置页可关） |
| 选下一处相同词 |
Ctrl+D 逐处追加相同词为选区，Ctrl+Shift+L 一次选中全部相同词 |
| 中文分词词级移动 |
Ctrl+方向在中文段按分词逐词跳转；可选 jieba 引擎（按需下载，支持本地路径离线安装），失败自动回退内置分词 |
| 查找与替换 |
大小写、全字与正则三开关，可在选定内容中查找，Ctrl+H 展开替换栏；阅读模式命中按字符高亮 |
| 跳转到行 |
Ctrl+G 输入源文件行号定位到当前文档该行（实时预览与阅读均可用，折叠节先展开再定位） |
| 快捷键管理 |
全部操作集中改绑（支持两段键），冲突检测、清空与恢复默认，清空后重启不回弹 |
| 功能 |
说明 |
| 表格编辑 |
规范表格以网格呈现：格内直接编辑、跨格拖选复制、行列增删与拖动重排，列宽按内容分配、短列保随字号的可读下限，离开表格后按整表高度优化；方向键可停靠前后边沿，插入或删除相邻普通空行；引用块与列表内的表格同样支持 |
| 列表与引用 |
Enter 延续结构、退格分层剥除、Tab 整行缩进，嵌套列表与引用完整支持 |
| Callout 提示块 |
> [!note] 标题 形式的 Obsidian Callout：13 个内置类型与别名在实时预览与阅读视图按各自底色、图标与标题呈现，富标题与多层嵌套；+／- 声明可按实例折叠，查找、链接与大纲定位进入时自动展开；右键创建／转换／改类型，类型菜单带实际配色预览；Obsidian 原名 CSS 变量（--callout-color 等）与 --callout-icon 自定义图标可定制外观；悬停／嵌入引用与 PDF 导出同样支持 |
| frontmatter 属性 |
YAML 头呈现为只读表格卡片，浮层内增删改属性与数组项，每笔操作一次撤销 |
| 功能 |
说明 |
| 双链与锚点 |
[[笔记]] 五形态双链，#标题 与 #^块id 锚点跳转落到目标位置，跳转后目标高亮提示 |
| 普通链接行号 |
[跳转](note.md:103) 点击后 Markdown 在 Vsidian 面板落到第 103 行、代码/配置等文本文件在原生编辑器 reveal 到该行（file.ts:103 同款）。行号越界打开后如实提示不静默钳到末行；行号与锚点混写（note.md:20#标题）按非法定位报错 |
| 短名与绝对路径引用 |
双链短名同目录未命中时可命中所属工作区根内唯一同名笔记（多个同名不冒充命中）；显式绝对路径双链（Windows 盘符或服务器路径）可跨工作区根、访问工作区外目标，跳转、悬停、嵌入、反链与更名更新全覆盖 |
| 双链输入联想 |
输入 [[]] 弹出文件候选（覆盖图片、PDF 等全部常用文件），#／^ 继续列出目标文档的标题与块候选；插入路径可选最短／相对（默认）／绝对三档（设置页「文件与链接」）；表格单元格与嵌入编辑内同样可用 |
| 复制块链接 |
右键任意块复制 [[笔记#^块id]]，块无 id 时自动生成；快捷键 Ctrl+Shift+C |
| 图片粘贴 |
Ctrl+V 落盘剪贴板图片并在光标处插入引用，存放位置与子路径可配置；链接格式可选 Markdown 直链（默认）或 ![[…]] 双链嵌入（路径原样保留空格） |
| 图片双链嵌入 |
![[图片.png]] 双链语法嵌入图片，与普通图片链接呈现行为一致：加载、失败提示、自动刷新与弹窗查看同款；悬停指向图片的双链直接显示图片本体 |
| 图片尺寸后缀 |
`![[图.png |
| 图片弹窗查看 |
悬停图片浮现按钮组，全屏弹窗内缩放、平移、刷新与导出原图；点击图片本体不再跳转到源码 |
| 嵌入资源刷新 |
磁盘图片被替换或删除后自动重载或提示找不到；顶栏刷新按钮随时手动刷新图片与图表，快捷键可绑定（默认未绑定） |
| 外链预览 |
悬停 http(s) 链接显示标题、摘要与域名卡片（默认关闭；受限抓取，不发送笔记内容与凭据）；「原网页」形态在浮层内沙箱显示网页本身，可一键退回卡片 |
| 搜索定位恢复 |
工作区搜索点击结果打开笔记后，命令「定位到搜索选中结果」把光标定位到匹配处（默认未绑定；VSCode API 限制不自动定位） |
| 功能 |
说明 |
| 悬停文档预览 |
Ctrl+悬停链接预览目标：笔记显示全文、章节或块引用，浮窗内可直接编辑保存；代码等文本文件按 VSCode 原生着色只读显示；PDF 分页浏览、文字可复制可缩放。实时预览、阅读与反链/出链面板均可用，可在设置改为直接悬停或整体关闭 |
| 跳转目标提示 |
悬停链接不弹预览浮层时，短暂停留显示目标路径与锚点的小浮标，双模式与链接面板均可用，可在设置关闭 |
| 正文文档嵌入 |
![[笔记]] 挂载卡片，卡片内可直接编辑并保存目标笔记，父文档不受牵连；![[文件.ts]] 与 ![[文件.pdf]] 以只读视图嵌入文本与 PDF，支持 #line=N／#range=B-E 行锚点；光标触及显形引用源码可原位编辑，混排、列表、引用块与表格单元格内均支持，逐层递归展开（默认三层） |
| 反链面板 |
侧栏显示当前笔记被哪些文档引用：按来源分组的上下文卡片，命中链接原文高亮，可排序与搜索，点击定位到引用处 |
| 出链面板 |
侧栏平铺当前笔记的全部链接（双链、链接、图片、引用定义），点击按链接实际锚点定位，断链弱化显示 |
| 引用自动更新 |
在 VSCode 内重命名或移动文件、文件夹与多文件时，指向它们的双链、链接与图片按新位置自动重算（短名仍唯一命中时不改动，目标越出工作区根时以绝对路径保留指向），一步撤销 |
| 功能 |
说明 |
| 代码块卡片 |
代码块收起为卡片：语言徽标、卡内行号、复制、折叠、阅读视图折行开关；语法配色跟随 VSCode 明暗主题 |
| 图表与公式 |
Mermaid 图表与 KaTeX 公式双视图渲染，图表可全屏弹窗缩放浏览并导出 SVG/PNG；外观「主题」页统一选择图表主题——安装提供主题的附加组件（如 Vsidian Codex Bridge）后即可选用 Codex 等主题 |
支持的围栏语言与别名见代码块语言清单，包括 Tcl、VHDL、项目配置语言及 C#、Kotlin、Swift、Dart、SPICE、Makefile、PHP、GraphQL 等，还有独立 PostgreSQL/MySQL/SQLite 与 JSONC/JSON5 方言；正文、Markdown 悬停与嵌入共用词法高亮。
| 功能 |
说明 |
| PDF 导出 |
命令面板与工具栏提供当前文档、当前选区、批量与合并四种导出；导出窗口内置按打印尺寸显示的真实 PDF 预览（可缩放、手动刷新）与纸张、页边距、缩放、页眉页脚、页码、标题书签等排版参数；正文与阅读模式同源渲染，表格、公式、图表与嵌入展开均入版；Remote SSH 远程工作区同样可用（PDF 在本机生成保存）。详见 PDF 导出说明 |
| 功能 |
说明 |
| 大纲面板 |
标题层级实时同步、点击跳转、拖拽整段重排、标题搜索、折叠滑块，行内样式与层级配色透传 |
| 功能 |
说明 |
| CSS 片段 |
设置页「外观」分页管理用户目录 .css 片段，跨项目逐项启停，支持 @import 嵌套导入、HTTPS 远程样式与在线字体 |
| 样式参考 |
「外观」分页离线查阅与搜索公开样式契约，契约 JSON 可导出供 AI 助手和外部工具使用 |
| 可读行宽 |
滑块同时约束实时预览与阅读的正文列宽，0 为铺满，正文列居中并避让大纲栏 |
| 界面语言 |
中英文界面即时切换，默认跟随 VSCode 显示语言 |
| 功能 |
说明 |
| 附加组件系统 |
声明附加组件身份的 VSCode 扩展安装后由 Vsidian 自动发现并注册，可贡献设置页、输入行为、代码块渲染、粘贴转换规则、只读引用视图（浮窗与嵌入挂载）、主题、命令与快捷键、右键菜单项、工具栏按钮与面板 |
| 管理与诊断 |
设置页提供组件启用开关、设置调整、输入行为排序与逐项关闭、故障原因查看与手动重试；组件故障时自动撤下其贡献，不影响其他组件与内置功能 |
| 代码块渲染接管 |
组件可为其声明的语言提供替代渲染（含 Mermaid），用户可按语言改选或交回内置；停用或故障后自动交回内置渲染 |
| 开发者 API |
API 参考、语义清单与开发指南维护在仓库 docs/addons/，变更记录见 CHANGELOG-API.md；稳定 API 自 1.1.0 起随版本发行并提供兼容承诺 |
各功能的完整行为、边界与全部设置项说明见 docs/features.md（中文）。
- 不支持 Obsidian 的 Canvas、白板与
.md 之外的笔记格式；不兼容 Obsidian 插件本体——Vsidian 有自己的附加组件体系（见上）。
- CSP 允许任意 https 图源（远程图床支持的设计代价，理论上可被用作跟踪像素）。
- 超长代码块跳过语法着色，回退纯文本卡片。
- 外部入口（工作区搜索、问题面板等）点击打开笔记不会自动定位到匹配——VSCode 公开 API 缺口（跟踪 vscode#289785），可用命令「定位到搜索选中结果」手动定位。
npm install # 安装锁定依赖
npm run compile # esbuild 构建 + tsc 类型检查
npm run test:unit # 单元测试（无 VSCode 宿主依赖）
npm run test:browser # Playwright 浏览器回归（首次需 npx playwright install chromium）
npm run test:integration # 真实 VSCode 宿主集成测试
npm run release:check # 打包 VSIX 与发布前检查
Windows 上集成测试默认在独立桌面启动真实 VSCode 宿主，不干扰当前桌面；无人值守环境的前台模式与分片运行见仓库内 test/integration/ 各启动器说明。发布流程、包体红线与样式契约门禁的约定见仓库内技能文档（.agents/skills/release/ 与 .agents/skills/style-contract/）。
问题反馈请到 Issues，版本历史见 CHANGELOG。
