HTML Atelier

在 Obsidian 里直接把 .html 当笔记来改。
点选页面上的文字、链接和图片直接编辑，保存修改。

产品主页 · 社区插件页 · 发布版本 · 反馈问题 · English

_{支持 .html / .htm · 界面中英双语 · 本地文件，无需账号或云端服务}

为什么是 HTML Atelier

• 点选页面，直接修改：选中页面上的文字、链接或图片，在侧栏表单里改，预览随输入更新。
• 支持 JS，样式更加丰富：页面可以使用完整 CSS 与可选页面脚本；脚本默认关闭，可在设置中开启，版式与交互比 Markdown 更自由。
• 草稿备份，不怕手抖改错：编辑时自动保存草稿快照，重开文件或重启后都能恢复；磁盘改动冲突可三方合并。
• 双向链接，构筑知识网络：笔记用 [[页面.html]] 链接 HTML 文件，反向链接与出链都在侧栏「链接」标签里，点击即可在来源笔记和目标之间跳转。

一眼看懂

• 主视图：预览 / 编辑 / 源码 / 分栏。
• 侧栏：标签页上方常驻搜索栏 + 编辑 / 大纲 / 修改 / 链接四个标签。
• 链接：反向链接 / 出链 / 引用资源三段，可折叠。
• 保存：只改你动过的那一段，其余内容原样保留。

一次修改，经历了什么

1. 打开 .html / .htm，页面在沙箱预览中渲染；页面脚本默认不执行。
2. 点选文字、链接或图片，侧栏切换到对应表单。
3. 修改时预览实时更新，未保存内容自动备份成草稿。
4. 保存：把改动拼回原始源码的对应区间，其余字符原样保留。
5. 若磁盘文件在你编辑期间被改动，保存前会提示冲突：三方合并、采用磁盘版本，或把草稿另存。

截图

_{编辑 选中标题，侧栏直接改文字  ·  分栏 源码与预览并排}

_{链接 反向链接 / 出链 / 引用资源  ·  嵌入 笔记中的页面滚动到锚点}

_{截图来自 HTML Atelier 2.3.0 的演示库，个别设置状态可能与默认值不同。}

快速开始

需要 Obsidian 桌面版 1.7.2 或更高版本，支持 .html、.htm，不支持移动端。

1. 安装插件：在 设置 → 第三方插件 → 浏览 中搜索 HTML Atelier，安装并启用。
2. 打开页面：打开库里的 .html 或 .htm 文件，页面显示在主工作区，侧栏工作台默认自动展开。
3. 开始编辑：切到 编辑，点选页面中的对象，在侧栏修改，然后点 保存。未保存的改动会自动备份。
4. 链接笔记：在 Markdown 笔记里写 [[页面.html]]（带扩展名），HTML 侧栏的「链接」里就会出现反向链接；页面里的 <a href> 会出现在出链。

.obsidian/plugins/html-atelier/
├── main.js
├── manifest.json
└── styles.css

```html-atelier
path: "Pages/weekly-report.html"
height: auto
anchor: summary
```

功能

预览与导航

• 沙箱预览静态 HTML，页面脚本默认关闭；支持缩放档位（25%–200%）、常用宽度（自适应 / 1440 / 768 / 390 / 自定义）和按文件记忆视口。
• 库内样式表（<link>、@import）内联进预览，图片等相对资源按页面目录解析；远程资源默认允许，可在设置中关闭。
• 支持页内锚点、库内链接、后退 / 前进与阅读位置记忆；引用的本地 CSS、图片变化时可自动刷新。
• 预览滚动条默认仿 Obsidian 样式（细圆角、透明轨道），深色页面自动反白；页面自带滚动条样式时保持页面原样。

可视化编辑

• 编辑单个文字片段，或切换到整段编辑跨内联格式改字；链接可改文字、地址或选择库内文件；图片可改地址、alt 或导入外部图片。
• 未受影响的源码区间保留原有标签、属性、注释、缩进、换行与实体写法；特殊字符按文本转义。
• 源码模式支持行号、软换行与刷新延迟；撤销 / 重做会合并连续输入。

侧栏工作台

• 搜索栏：在当前草稿内查找替换，支持区分大小写与全部替换；跨格式边界命中会跳过并提示。
• 编辑 / 大纲 / 修改 / 链接：改选中对象、跳转标题与文案、定位并恢复文字改动；「链接」里是反向链接、出链与引用资源。
• 工作台底部显示保存按钮、保存 / 草稿 / 冲突状态与文件缺失提示。

草稿与冲突

• 草稿备份默认开启，按设备标识存放于 .obsidian/plugins/html-atelier/drafts/；重新打开文件（包括重启后）自动恢复。
• 磁盘内容与上次保存基准不一致时提示冲突：三方合并（我的草稿 / 磁盘版本 / 共同基准）、使用磁盘版本，或把草稿另存为独立文件。
• 更多 → 草稿管理… 可搜索、打开原文件或丢弃草稿；另存为支持重写本地相对引用，不复制资源文件。

双向链接

• 笔记用 [[页面.html]]（带扩展名）链接 HTML 文件，即接入 Obsidian 原生的出链 / 反向链接索引，索引变化会实时刷新。
• 侧栏「链接」标签分三段：反向链接（点击打开来源笔记）、出链（扫描页面 <a href>，同目标合并计数，点击跳转目标）、引用资源；三段均可折叠。
• 「定位」会在预览里高亮该链接，同目标出现多次时循环显示 1/N、2/N…；文字链接居中选中，图片/图标等无文字链接滚动到位并描边闪烁；行卡片支持 Enter / 空格。
• template / svg 内的链接不进入清单；脚本模式沙箱不可达时回退到源码定位。

链接、锚点与分享

• Wiki / Markdown 链接指向 HTML 文件时在插件视图内打开；页面内锚点与库内链接可在预览中直接跳转。
• 更多菜单可复制页面链接、HTML 嵌入代码，或在系统浏览器打开当前文件；复制章节链接需要先选中锚点。
• 嵌入支持高度、宽度、锚点与工具栏显隐，默认显示文件名与刷新 / 打开按钮。

安全模型

HTML 文件本身可以携带脚本。HTML Atelier 默认只显示页面，不执行页面里的代码。

• 「允许页面脚本」默认关闭，只应对可信文件开启；开启后静态本地资源会以 data URL 内联，运行时动态资源和跨文件模块导入不会。
• 脚本模式是「隔离」而不是「离线」：网络资源仍默认允许，远程脚本与请求也会被放行；处理不可信页面时建议同时关闭网络资源。

边界

• 可视化编辑面向页面文字、链接地址与图片属性，不编辑 CSS、任意 HTML 结构、表单字段值或 SVG 内文字；这些请用源码模式。
• 片段编辑遵循原文字节点；整段编辑保留内联标签，但改动文字在格式区间之间的分布可能变化。
• 仅支持桌面版 Obsidian；外部浏览器打开时，脚本与网络行为由浏览器决定。

常见问题

实现（给开发者）

• 解析与定位：parse5 携带源码位置解析，建立文字节点到源码区间的映射；无法对齐时提示改用片段编辑。
• 局部改写：编辑形成区间补丁（src/core/patch.ts，段落规划见 src/parsing/paragraphEdit.ts），保存时只替换受影响区间。
• 隔离预览：srcdoc + nonce + 沙箱 iframe + CSP；脚本模式切换为不透明源沙箱并内联静态本地资源。
• 双向链接：反向链接从 Obsidian 原生 resolvedLinks 反演，出链复用 LinkRouter 的解析器；同目标合并计数，定位采用循环高亮。
• 草稿与冲突：草稿记录含原始源码、工作副本、校验和与设备标识，按「临时文件 → 校验 → 正式文件」写入，冲突时使用 diff3 三方合并。

开发

npm ci
npm run lint
npm run check
npm test
npm run build
node tests/browser-check.mjs
node tests/sidebar-regression.mjs

• 构建产物为 main.js（含打包后的 Worker），与 manifest.json、styles.css 一起安装。
• 浏览器检查默认使用 Microsoft Edge；可用 HTML_ATELIER_BROWSER 指定其他 Chromium 浏览器。

许可证

• 本项目以 MIT 许可证 发布；第三方依赖许可见 THIRD-PARTY-NOTICES.txt。
• 站点位于 site/；README 使用的截图与图解位于 assets/readme/。

_{HTML Atelier 是社区插件，与 Obsidian 官方无隶属关系。Obsidian 是 Dynalist Inc. 的商标。}