HTML V Editor

HTML V Editor 是一个 Obsidian 桌面端插件，用来在 vault 内直接预览、编辑和保存 .html / .htm 文件，并为 Markdown 中的 html-v 代码块和 HTML 嵌入提供可视化编辑体验。

English: HTML V Editor is a desktop-only Obsidian plugin for previewing, visually editing, and saving .html / .htm files inside your vault. It also supports editable Markdown html-v code blocks and embedded HTML files.

功能亮点 / Features

• 在 Obsidian 中打开 .html / .htm 文件，并在 Preview、Edit、Source 三种模式之间切换。
• 使用本地打包的 HugeRTE 作为可视化 HTML 编辑器，不依赖 CDN。
• 支持 Markdown html-v fenced code block 的阅读模式和 Live Preview 渲染。
• 支持 Markdown 中嵌入 HTML 文件，并从嵌入预览进入编辑。
• 支持把当前 HTML 导出复制为 Markdown 或纯文本，覆盖 HTML tab、html-v block 和嵌入 HTML。
• 提供 Safe / Sandbox / Trusted 三档预览安全模式。
• 支持 HugeRTE checklist、特殊字符选择器、图片路径处理、表格内 checklist。
• 内置 HTML V Tasks / Links 侧栏：Tasks tab 可聚合 HTML checklist、html-v block checklist 和普通 Markdown task；Links tab 可发现独立 HTML 文件中的内部链接。
• Tasks tab 支持状态、来源、tag、project、当前文件和分页过滤；Links tab 支持搜索、状态、当前 HTML 文件和分页过滤，并可打开已解析的 vault 链接。

English features:

• Open .html / .htm files in a custom Obsidian view.
• Switch between Preview, visual Edit, Source, and Save.
• Bundle HugeRTE locally with no CDN dependency.
• Render and edit Markdown html-v fenced code blocks.
• Render and edit embedded HTML files.
• Copy the current HTML as Markdown or plain text from HTML tabs, html-v blocks, and embedded HTML.
• Use Safe, Sandbox, or Trusted preview modes.
• Use the built-in HTML V Tasks / Links side panel to manage checklist tasks and discover internal links from standalone HTML files.

安装 / Installation

可直接在 Obsidian 的社区插件市场搜索 HTML V Editor 安装，也可以使用 GitHub Release 资产手动安装。

Manual installation:

1. Download the release assets from GitHub.
2. Copy these files into <vault>/.obsidian/plugins/html-v-editor/:

main.js
manifest.json
styles.css

3. Restart Obsidian or reload community plugins.
4. Enable HTML V Editor in Obsidian settings.

本地安装细节见 docs/local-install.md。

使用 / Usage

打开 vault 中的 .html 或 .htm 文件后，插件会显示 HTML V Editor 标签页。顶部按钮用于切换：

• Preview：预览 HTML 内容。
• Edit：使用 HugeRTE 可视化编辑。
• Source：直接编辑 HTML 源码。
• Save：写回当前文件。

在 Markdown 文件中可以使用：

```html-v
<table>
  <tr><td>Hello HTML V</td></tr>
</table>
```

也可以嵌入 vault 内 HTML 文件：

![[example.html]]

English usage: open an HTML file in your vault, switch modes from the toolbar, edit with HugeRTE or source mode, then save back to the same vault file. Markdown html-v blocks and embedded HTML files can be edited from reading or Live Preview surfaces.

HTML V Tasks / Links

HTML V Tasks 是插件内置任务面板，用于集中查看和勾选：

• HTML 文件中的 HugeRTE checklist。
• Markdown html-v code block 中的 checklist。
• 普通 Markdown task。

任务面板支持：

• All / Open / Done 状态过滤。
• 只看 HugeRTE / HTML V checklist。
• 只看当前文件，以及当前 Markdown 文件嵌入的 HTML 文件。
• 按来源、#tag、#project/name 过滤。
• 分页渲染大量任务条目。

Links tab 当前用于查看独立 .html / .htm 文件中的 <a href>：

• 支持 Obsidian wiki link 和 vault 相对 Markdown / HTML 路径。
• 可按 All / Internal / Attention / External、关键字和当前 HTML 文件筛选。
• 已解析链接可由用户主动打开；外部、危险、纯锚点和未解析链接只显示状态与原因，并可复制原始地址。
• Links 同时保留独立 HTML、html-v block 与 HTML embed 的来源上下文；同一嵌入文件因此可能显示为不同位置的记录。
• 预览内链接点击和 hover 仅在 Trusted 或显式开启同源权限且未运行脚本的 Sandbox 中启用；Safe 保持 iframe 隔离，可通过 Links tab 打开内部目标。
• 命令面板提供 Open HTML V links；右键 HTML 文件可选择 Show HTML links in HTML V panel。
• Links 是插件自有只读发现面板，不写入 Obsidian 核心 Backlinks、Graph 或搜索索引。

English: the Links tab indexes <a href> from standalone .html / .htm files, Markdown html-v blocks, and HTML embeds. It resolves Obsidian wiki links and vault-relative Markdown / HTML paths, lets users filter and explicitly open resolved targets, and reports external, blocked, anchor-only, and unresolved URLs without navigating them. Preview click and hover are available only in Trusted mode or in a script-free Sandbox with explicitly enabled same-origin access; Safe mode remains isolated and can use the Links tab instead. It is a plugin-owned read-only panel and does not write to core Backlinks, Graph, or search indexes.

设置 / Settings

插件设置页目前按中文分组整理，覆盖：

• 编辑器与 Source 后端。
• HugeRTE checklist 按钮。
• 特殊字符按钮、默认字符组和自定义字符。
• 任务面板索引范围、默认状态、分页大小。
• Live Preview 行为。
• Safe / Sandbox / Trusted 安全选项和 trust 规则。

详细说明见 docs/settings-guide.md。

安全说明 / Security

默认 Safe 模式会使用 DOMPurify 清理 HTML，移除脚本和高风险属性，并在不允许脚本执行的 iframe 中渲染。

Sandbox 和 Trusted 模式适用于你信任的内容。Sandbox 中的脚本始终运行在不透明 origin，不能与 same-origin 同时启用；需要同源脚本的本地 HTML 应明确改用 Trusted。Sandbox 的表单和弹窗默认关闭，必须由用户单独开启。

English: Safe mode sanitizes HTML with DOMPurify and renders it in a restricted iframe. Sandbox scripts always run with an opaque origin and cannot be combined with same-origin access; local HTML that truly needs both must be explicitly opened in Trusted mode. Sandbox forms and popups are disabled by default. Sandbox and Trusted modes should only be used with content you trust.

字体策略 / Font Policy

插件不打包或再分发字体文件。HugeRTE 的字体菜单和编辑器界面只主动声明 Inter、Noto、思源、Sarasa Gothic、JetBrains Mono、Fira Code、LXGW WenKai Mono 等开源字体族，并保留通用字体回退。

English: The plugin does not bundle or redistribute font files. Editor font menus and UI styles prefer open-source font families and always include generic fallbacks.

发布状态 / Release Status

当前插件版本：1.2.1

当前状态：

• 已发布到 Obsidian 社区插件市场。
• HugeRTE 运行资源已经打入标准发布资产，不依赖 CDN 或额外的 hugerte/ 目录。
• GitHub Release 提供标准 main.js、manifest.json、styles.css 资产。

开发 / Development

开发前先阅读 架构概览 和 开发、测试与发布。二者说明多 surface 约束、自动验证、本地 vault 安装、发布预演与公开/私有文档边界。

Install dependencies:

npm ci

The checked-in .npmrc keeps the Obsidian development package's strict CodeMirror peer metadata from making clean installs non-reproducible. It only affects development dependency resolution.

Build:

npm run build

Audit active font references and bundled font files:

npm run audit:fonts

Create local release package:

npm run release

Report artifact sizes:

npm run size

Copy to a local vault plugin folder:

$env:OBSIDIAN_PLUGIN_DIR = "C:\Path\To\Vault\.obsidian\plugins\html-v-editor"
npm run copy:local

License

MIT