HTML Works

Open .html and .htm files in Obsidian, preview their contents, and edit their source in the native editor.

HTML Works and Doc Works are a matching pair: separate plugins with the same compact toolbar, native theme colours, light/dark paper options, file creation commands, and in-vault editing. Neither requires the other.

Use

• Open an HTML file from the file explorer or a note link. It opens in Preview by default.
• Click Source to edit, then Preview to see the result. The header reading/editing button also switches modes. Each tab remembers its mode.
• Source editing uses an actual MarkdownView subclass and Obsidian's own editor, autosave, undo history, search, and editor extensions. Enable Vim in Obsidian's Editor settings as usual. Plugins that explicitly restrict themselves to .md files or the markdown view type can still exclude HTML Works; compatibility with every editor plugin is not guaranteed.
• Use HTML Works: New HTML file or a folder's context menu to create a file.
• Use the Light / Dark toolbar button to switch paper theme. The opening mode and paper theme are also available under Settings → HTML Works.

The preview handles complete HTML documents and HTML fragments, including styles, tables, and images. Page styles are isolated from Obsidian. Preview formatting never rewrites your HTML; only source edits are saved. Untouched source retains its exact text, including CRLF line endings.

Images

Relative image, stylesheet and CSS url() paths resolve from the HTML file's own folder, including srcset candidates. Paths containing spaces and inline data images are supported. A relative <base href> is resolved against that folder.

Local vault files are embedded as data URLs in the disposable preview. This lets them load inside the sandbox without giving the page access to the parent application. The HTML source keeps its original paths.

The preview never uses the network. Remote images, stylesheets, fonts and links do not load; a remote image shows its alt text unless a vault copy is available. HTML Works only reads vault files to find one, in this order:

1. A choice made with Images → Choose vault image. It is stored in plugin settings, follows file renames, and does not change the source.
2. The Doc Works attachments layout: a <name> attachments folder beside <name>.html, with remote images numbered by first use as image-1.png, image-2.jpg and so on.

Scripts

Scripts start disabled. Scripts off enables them for that individual trusted file; Scripts on disables them again. Even trusted pages remain sandboxed without access to the parent app, popups, forms, or top-level navigation. Embedded frames and objects are blocked. Trusted scripts get no network access either: requests, WebRTC, and navigating the preview to another page are all blocked. Script-dependent content may require enabling scripts. Preview scripts stop when you switch to source.

Install

From this project:

npm ci
npm run install:plugin -- /path/to/vault

Then enable HTML Works in Settings → Community plugins. For manual installation, copy main.js, manifest.json, and styles.css into <vault>/.obsidian/plugins/html-works/. Disable another plugin's HTML file handling if it already owns these extensions.

Development

npm run dev
npm test
npm run typecheck
npm run lint
npm run build
npm run check:live

To check real course exports without modifying them:

HTML_WORKS_NOTES=/path/to/course npm test

Automated checks cover preview policies, iframe lifecycle, theme colours, image paths and overrides, source fidelity, and the optional real-file corpus. check:live uses a disposable tab and scratch HTML/SVG files in the open vault to check source-to-preview switching, editing, browser image loading, sandboxing, and the toolbar theme switch. It cleans up its scratch files and restores the previous theme afterward. Install and reload the latest build before running it. Native Vim input, third-party editor extensions, and mobile behaviour require separate manual checks.

For development, node scripts/reload-live.mjs temporarily loads the workspace build into the running app through its native plugin loader, preserving open HTML tabs. It does not replace installed files; restarting or reloading the plugin returns to the installed build. Use the installer for a persistent update.

GPL-3.0, like Doc Works.