README file from
GithubHTML Effectiveness for Obsidian
English
Render spatial HTML content inside notes AND view standalone HTML files within Obsidian. Based on the html-effectiveness methodology.
What It Solves
1. Obsidian cannot render spatial HTML content natively
Markdown is linear, but information like comparisons, timelines, and dashboards needs spatial layout that only HTML can express. This plugin lets you render these structures directly inside your notes using html-effect code blocks.
2. HTML files generated by html-effectiveness cannot be viewed in Obsidian
AI-generated HTML reports (industry digests, analysis reports, data dashboards, etc.) open fine in a browser, but Obsidian only shows their source code. The plugin provides a dedicated HTML file viewer that renders these files correctly, including images, styles, and interactive elements.
3. Relative-path images do not display in Obsidian
Other HTML preview tools fail to load relative-path images such as src="images/foo.png" when opening HTML files inside Obsidian. This plugin automatically rewrites relative paths to Obsidian-recognized resource URLs so images display correctly.
Features
html-effect code block (use directly in notes)
| Template | Description |
|---|---|
| Compare — side-by-side comparison | Left/right split, ideal for comparing options or parameters |
| Timeline — timeline view | Vertical timeline with date markers |
| Diagram — ASCII diagram | Monospace text box for simple architecture diagrams |
| Report — KPI report | Data cards + body text, ideal for dashboards |
| Slides — paged slides | Page up/down navigation, ideal for presentations |
HTML file viewer
Open .html files directly in Obsidian with full rendering:
- Open: right-click a
.htmlfile → "Open with HTML Effectiveness" - Command palette: "Open current file in HTML viewer" (shown only for
.htmlfiles) - Auto-association: clicking a
.htmlfile opens it with this plugin - Image support: relative-path images are rewritten to Obsidian resource URLs
- Live refresh: the view updates automatically when the
.htmlfile is edited - Interactivity: the iframe sandbox includes
allow-scripts, so JavaScript interactions work - WYSIWYG text editing: click "✏️ Edit" to edit the rendered page in place — click any text and type, formatting stays intact. Save with Ctrl/Cmd+S or "💾 Save" (overwrites the original file). "</> Source" switches to raw HTML text editing
- Edit commands: "Toggle edit/preview mode for HTML viewer" and "Save HTML file (edit mode)" in the command palette
More
- Export note: the "Export note as HTML" command exports the current note to a standalone HTML file using the selected theme
- Insert templates: 6 quick commands insert common template code blocks
- Theme setting: Auto (follows the current Obsidian theme), Dark, or Light for rendered blocks and exported HTML
Usage
Insert an html-effect code block in a note
```html-effect
compare
Left content
---
Right content
```
```html-effect
timeline
- [2026-01] Event one
- [2026-03] Event two
- [2026-06] Event three
```
```html-effect
---
type: report
---
##
- 85%: completion rate
- $2.5B: market size
# Report title
Body content...
```
View an HTML file
In the Obsidian file explorer:
- Right-click a
.htmlfile → "Open with HTML Effectiveness" - Or select the file and open the command palette → "Open current file in HTML viewer"
Commands
| Command | Description |
|---|---|
| Open current file in HTML viewer | Open the current file in the HTML viewer |
| Toggle edit/preview mode for HTML viewer | Switch the HTML viewer between editing and preview |
| Save HTML file (edit mode) | Overwrite-save the file being edited |
| Export note as HTML | Export the current note as a standalone HTML file |
| Compare | Insert the Compare template |
| Timeline | Insert the Timeline template |
| Report | Insert the Report template |
| Slides | Insert the Slides template |
| Diagram | Insert the Diagram template |
Changelog
1.2.0
- Interactive pages actually work: the preview iframe now also allows forms, modal dialogs, popups and downloads. Previously
submit(),alert()/confirm(),window.open()and<a download>were silently blocked by the sandbox, which looked like a broken page - Dark-mode export: the standalone HTML written by "Export as HTML" follows the reader's
prefers-color-scheme, and itslangattribute matches the UI language instead of always beingzh
1.1.1
- Fix viewport-layout HTML: pages with a
<canvas>orhtml/body { height: 100% | 100vh }are no longer wrapped in the zoom container, so canvas apps keep a 1:1 frame and pointer hit-testing stays accurate - Opt-out meta: add
<meta name="he-no-zoom">to any HTML file to skip the zoom wrapper - Bilingual UI: toolbar, commands, notices and settings follow Obsidian's UI language
1.1.0
- WYSIWYG text editing: edit the rendered page in place (contenteditable) via the toolbar; "</> Source" edits raw HTML. Ctrl/Cmd+S or Save overwrites the original file
- Unsaved changes are confirmed before switching back to preview
1.0.24
- Adaptive fit-to-width zoom on open; removed stale localStorage zoom
- Robust flex-based view container layout
1.0.23
- Bilingual README, English UI copy
Installation
Requires Obsidian 1.8.7 or later.
From Obsidian Community Plugins
Settings → Community Plugins → Browse → Search "HTML Effectiveness"
Manual / BRAT
- Install BRAT
- Add the repository:
yanqingwang/obsidian-html-effectiveness
Development
cd html-effectiveness-plugin
npm install
npm run dev # watch mode
npm run build # production build
License
MIT
Copyright (c) 2026 rosswang (Heart and Road Ltd)
Issues & Feedback
- GitHub Issues: https://github.com/yanqingwang/obsidian-html-effectiveness/issues
- Email: [email protected]
中文
在 Obsidian 中渲染空间化 HTML 内容 + 浏览独立 HTML 文件。基于 html-effectiveness 方法论。
解决的问题
1. Obsidian 无法直接渲染空间化 HTML 内容
Markdown 是线性的,但对比、时间线、仪表盘等需要空间布局的信息用 HTML 才能表达。本插件让你在笔记中用 html-effect 代码块直接渲染这些结构。
2. html-effectiveness 生成的 HTML 文件无法在 Obsidian 中查看
AI 生成的 HTML 报告(行业周报、分析报告、数据仪表盘等)在浏览器中打开正常,但在 Obsidian 中只能看到源码。插件提供了专用的 HTML 文件查看器,正确渲染这些文件,包括图片、样式、交互元素。
3. 相对路径图片在 Obsidian 中无法显示
其他 HTML 预览工具在 Obsidian 中打开 HTML 文件时,src="images/foo.png" 这类相对路径的图片会加载失败。插件自动将相对路径转换为 Obsidian 可识别的资源 URL,图片正常显示。
功能
html-effect 代码块(在笔记中直接使用)
| 模板 | 说明 |
|---|---|
| Compare —— 双栏并排对比 | 左右分栏,适合方案对比、参数对照 |
| Timeline —— 时间线视图 | 垂直时间线,带日期标记 |
| Diagram —— ASCII 图示 | 等宽字体文本框,可画简单架构图 |
| Report —— KPI 报告 | 数据卡片 + 正文,适合仪表盘 |
| Slides —— 可翻页幻灯片 | 上下翻页,适合演示 |
HTML 文件查看器
在 Obsidian 中直接打开 .html 文件,完美渲染:
- 打开方式:右键 .html 文件 → "Open with HTML Effectiveness"
- 命令面板:"Open current file in HTML viewer"(仅 .html 文件显示)
- 自动关联:点击 .html 文件自动用本插件打开
- 图片支持:相对路径图片自动转换为 Obsidian 资源 URL
- 实时刷新:编辑 .html 文件后视图自动更新
- 交互支持:iframe sandbox 包含 allow-scripts,支持 JavaScript 交互
- 所见即所得编辑:点击 "✏️ Edit" 直接在渲染页面上改文字(点哪改哪,样式保持不变),Ctrl/Cmd+S 或 "💾 Save" 覆盖保存原文件;"</> 源码" 切换为原始 HTML 文本编辑。有未保存修改时切换会先确认
- 编辑命令:命令面板提供 "Toggle edit/preview mode for HTML viewer" 与 "Save HTML file (edit mode)"
其他
- 导出笔记:"Export note as HTML" 命令使用所选主题将当前笔记导出为独立 HTML 文件
- 插入模板:6 个快捷命令插入常用模板代码块
- 主题设置:自动(跟随当前 Obsidian 主题)、深色或浅色,适用于渲染块和导出的 HTML
使用方法
在笔记中插入 html-effect 代码块
```html-effect
compare
左侧内容
---
右侧内容
```
```html-effect
timeline
- [2026-01] 事件一
- [2026-03] 事件二
- [2026-06] 事件三
```
```html-effect
---
type: report
---
##
- 85%:完成率
- $2.5B:市场规模
# 报告标题
正文内容...
```
查看 HTML 文件
在 Obsidian 文件管理器中:
- 右键
.html文件 → "Open with HTML Effectiveness" - 或选中文件后打开命令面板 → "Open current file in HTML viewer"
命令
| 命令 | 说明 |
|---|---|
| Open current file in HTML viewer | 在 HTML 查看器中打开当前文件 |
| Toggle edit/preview mode for HTML viewer | 在 HTML 查看器的编辑与预览之间切换 |
| Save HTML file (edit mode) | 覆盖保存正在编辑的文件 |
| Export note as HTML | 导出当前笔记为独立 HTML |
| Compare | 插入 Compare 模板 |
| Timeline | 插入 Timeline 模板 |
| Report | 插入 Report 模板 |
| Slides | 插入 Slides 模板 |
| Diagram | 插入 Diagram 模板 |
更新日志
1.2.0
- 交互页面真正可用:预览 iframe 现允许表单、模态对话框、弹窗和下载;此前这些能力被沙箱静默拦截,看起来像页面坏了
- 导出支持深色模式:「导出为 HTML」生成的独立页面跟随系统深浅色,
lang属性随界面语言而不是固定为zh
1.1.1
- 修复自带视口布局的 HTML:含
<canvas>或html/body { height:100% | 100vh }的页面不再被包进缩放容器,画布应用保持 1:1,点击命中不再偏移 - 关闭缩放的开关:在任意 HTML 中加入
<meta name="he-no-zoom">即可跳过缩放包装 - 中英文界面:工具栏、命令、提示与设置页跟随 Obsidian 界面语言
1.1.0
- 应用内编辑:通过工具栏在查看器中直接编辑 HTML 源文本,Ctrl/Cmd+S 或保存按钮覆盖保存原文件
- 切回预览前如有未保存修改会先确认
1.0.24
- 打开时自适应宽度缩放,移除旧的缩放持久化
- 更稳健的 flex 视图容器布局
1.0.23
- 双语 README,英文界面文案
安装
需要 Obsidian 1.8.7 或更高版本。
从 Obsidian 社区插件安装
设置 → 社区插件 → 浏览 → 搜索 "HTML Effectiveness"
手动安装 / BRAT
- 安装 BRAT
- 添加仓库:
yanqingwang/obsidian-html-effectiveness
开发
cd html-effectiveness-plugin
npm install
npm run dev # 监听模式
npm run build # 生产构建
许可证
MIT
Copyright (c) 2026 rosswang (Heart and Road Ltd)