Obsidian HTML reader Plugin

This is a plugin for Obsidian (https://obsidian.md). Can open document with .html and .htm file extensions.

• How to use
• Install this plugin from Obsidian
• Manually installing the plugin
• HTML Reader Settings
  • General Settings
  • Hotkeys and Touch Gestures Settings
• More Options
• Form State Persistence
• Auto Reload On File Change
• How to build this plugin from source code
• Known issues

How to use

1. Put .html or .htm files to any obsidian-html-plugin installed vault folder
2. Click any HTML or HTM item to open it
3. Reading

Install this plugin from Obsidian

1. Head to ⚙"Settings" ⇨ "Community plugins" options page, make sure "Restricted mode" is turned off.
2. Click Browse button to open Community plugins browsing dialog.
3. Search for this plugin "HTML Reader" and click the corresponding result item.
4. Click Install button to install this plugin.
5. Once installed, click Enable button to enable this plugin.
6. Or, enable this plugin "HTML Reader" from the "Installed plugins" list of "Community plugins" options page.

Manually installing the plugin

1. Copy the main.js and manifest.json files from Releases list to your vault <path>/<to>/<vaultFolder>/.obsidian/plugins/obsidian-html-plugin/.
2. Relaunch Obsidian.
3. Head to ⚙"Settings" ⇨ "Community plugins" options page, make sure "Restricted mode" is turned off and enable this plugin "HTML Reader" from the "Installed plugins" list of "Community plugins" options page.

HTML Reader Settings

1. Head to ⚙"Settings" ⇨ "Community plugins" options page, find the settings icon ⚙ of "HTML Reader" item, then click it.
2. Or, Head to ⚙"Settings" ⇨ click "HTML Reader" item on the bottom of left panel under the "Community plugins" group after enabled it.

General Settings

Operating Mode

Set Operating Mode for this plugin to protect user and app.

Comparsion

	Images	Styles	Scripting	DSD*	CSP#	HTML Sanitization	Isolated
Text Mode	No	No	No	Yes	Yes	Yes	Yes
High Restricted Mode	Yes[1]	Partial	No	Yes	Yes	Yes	Yes
Balance Mode	Yes	Yes	No	Yes	Yes	Yes	Yes
Low Restricted Mode	Yes	Yes	Partial[2]	Yes	No	No	Yes
Unrestricted Mode	Yes	Yes	Yes[3]	Yes	No	No	Yes

*: Declarative Shadow DOM
#: Content Security Policy
[1]: The external image sources would be blocked by CSP.
[2]: The script codes inside <script> and external script files are still not executable.
[3]: The external script files may not executable due to Obsidian's limitation.

Detail Explanation

1. Text Mode - Highly recommended for the files came from untrusted source! This mode almost sanitized all visual effects, script codes, and styles out. eanwhile, it keeps text parts for reading the content of HTML files with HTML layout elements.

2. High Restricted Mode - This mode recommended for the user who wants more security. It would keep custom elements but sanitize unsafe HTML elements out, as well as unsafe attributes and their contents. The external image sources would be blocked by CSP, and the images are only available from the HTML files themselves.

3. Balance Mode - This mode is the default mode for this plugin. It would keep all custom elements and HTML elements, but sanitize unsafe attributes and their contents out.

4. Low Restricted Mode - This mode would not sanitize anything, all elements and their content would be keeped. The script codes inside <script> still not executable, nor the external script files.

5. Unrestricted Mode - This mode is very dangerous and may cause the Obsidian app crash, THE OBSIDIAN AND THIS PLUGIN CANNOT ASSUME RESPONSIBILITY OR LIABILITY FOR SWITCHING TO THIS MODE . It would not sanitize anything, all elements and their content would be keeped. The Obsidian app itself might adjust something. The external script files may not executable due to Obsidian's limitation. Strongly recommended not switching to this mode for normal usage.

   If you encounter troubles after switch to this mode, it is recommended to take these recovery steps:

   • Turn back to previous file which can open normally.
   • Delete or move the bad opened file to trash can. Otherwise, Obsidian would still open it after re-launched.
   • Return to this settings page to switch another Operating Mode.

   Sometimes you still cannot see what you want, then you should check the content of HTML file. This mode is just leave the content alone (only adjust the external link anchor tags to let them open in default browser windows), but the file might has some self-contained security protection facilities (such as CSP) and they would block something to avoid XSS attacks. If you find something like <meta http-equiv="Content-Security-Policy" /> inside the HTML file, it means the file is protected by CSP mechanism. You might

   • Modify or remove the CSP <meta> tag by hands.
   • Change the capture settings of the original web page saving app to disable CSP or something else, and re-save the web page.

Terms Explanation

This section would try to explain some terms used by Operating Mode more detail. You can ignore some terms without bold font face (they are technical terms).

1. Styles - It means HTML CSS styles. They are almost safe to use, but CSS Injection or CSS Keylogger would steal something, so some user interactive elements would be disabled at Balance Mode and High Restricted Mode .
2. Scripting - It means Javascript and very dangerous. Even some script codes would executable at Low Restricted Mode and Unrestricted Mode, this does not mean they can work very well. More complex of script codes, less chances they can work normally. If you want the script codes work as you wish, you shall rewrite them and related modules to satisfy Obsidian platform, because there are many different aspects between Obsidian platform and normal browsers.
3. DSD - It means Declarative Shadow DOM.
4. CSP - It means Content Security Policy. It provides some “binding operational directives” to tell Obsidian how to treat some resources. Its rules are different with others used by normal browsers and websites, the 'self' setting is almost meaningless for Obsidian.
5. HTML Sanitization - This mechanism would physically sanitize unsafe content out when loading HTML files, and there are different configurations among three modes. The sanitization configurations are progressive and may change with version iteration. If you think some tags or attributes shall not be sanitized, you can create a new issue in Issues page to let me know.
6. Isolated - The CSS styles of HTML files shall be isolated against with other parts of Obsidian, otherwise the Obsidian's layouts might be disarranged or font faces might become ugly. The disadvantages of CSS isolation might cause some CSS effects lost, such as :target pseudo-class event would never be fired. You can get more details from the CSS Isolation wiki page.
7. Custom Element - It means the HTML tags look like <xxx-yyy> and they are often incorporated with related javascript codes. Therefore, when the scripting is disallowed, the custom HTML tags are almost useless and would act as pure containers.

Background Color

Set HTML <body> element background color forcely.

Extra File Extensions

Open HTML format files with user defined file extensions (list of comma separated strings). Change this setting may cause other plugins un-workable, so you shall know very clearly what you are doing. Remember to relaunch the Obsidian app after change this setting!

MHTML File Format Support

Support with MHTML file format (.mht and .mhtml). Enable this option would convert the MHTML file format to HTML file format on the fly while opening the MHTML file each time. Therefore it would waste time on converting MHTML content! This option would override the 'Extra File Extensions' setting, and it also might cause other plugins un-workable. Remember to relaunch the Obsidian app after change this setting.
NOTE1: It is preferred to convert MHTML files to HTML files outside this plugin, then save back the converted HTML files to vault(s). It would save much computing time of the converting procedure when you have to open these MHTML files in a high frequency.
NOTE2: These two converter tools may help you.

1. mhtml-to-html: https://github.com/gildas-lormeau/mhtml-to-html, this project contains command line applications and library, and you can download it from Releases. By the way, this plugin also use this library to convert MHTML files.
2. Mhtml Wizard: https://erwannlc.github.io/mhtml-wizard/, this web app can convert MHTML file(s) online.

Hotkeys and touch gestures settings

Almost all keyboard hotkeys are taken from Obsidian's global hotkey settings, so you shall modify them via ⚙"Settings" ⇨ "Hotkeys" options page.
That means this plugin does not design any new configuration interface for keyboard hotkeys. And it just show the first two settings of corresponding hotkeys with readonly mode.

Search document text

Search current file.

Zoom in document

Zoom in current file.

Zoom out document

Zoom out current file.

Reset document zoom

Reset current file zoom.

Quick document zoom in and out

Zoom the document using Ctrl + Wheel (zoom in: ↑, zoom out: ↓), or using the trackpad/touch screen/touch panel two-finger pinch-zoom gesture (zoom in: ← →, zoom out: → ←).

More options

After a HTML file opened, the three dots ⋮ "more options" menu icon on right-upper corner of tab would be added some menu items.

Find...

Open search bar.

Zoom in

Zoom in current file.

Zoom out

Zoom out current file.

Reset zoom

Reset current file zoom.

Form State Persistence

Interactive HTML files (dashboards, calculators, forms) normally reset to their default values every time they are reopened. With this feature, the plugin remembers what the user changed:

1. Move a slider, type a value, tick a checkbox, pick a select option…

2. About 1 second after the last change, the plugin writes the current state of all form controls into the HTML file itself, as a single inert JSON block placed right before </body>:

   <script type="application/json" id="ohp-form-state">{"#mySlider":{"v":"75"}, ...}</script>
   

3. The next time the file is opened, the saved values are restored and synthetic input/change events are dispatched, so the page's own scripts (charts, computed outputs) react as if the user had entered the values manually.

Because the state lives inside the file, it travels with it — vault sync (iCloud, Obsidian Sync, git…) carries the state to other devices. The rest of the file is never touched: only the JSON block is inserted or replaced.

Details and limitations:

• Persisted controls: <input> (including range, number, checkbox, radio, date, …), <textarea>, <select> (including multiple). Controls are identified by their id, or by document position when they have no id.
• Never persisted: type="password", type="file", and type="hidden" inputs.
• Works only for plain-text .html/.htm files — not for SingleFileZ or MHTML files.
• Works in every Operating Mode except High Restricted and Text (those modes disable form controls anyway). Note that in the default Balance mode text inputs are read-only by design, but sliders, checkboxes, radios and selects still work and are persisted.
• Pending changes are flushed when the file view is closed.
• Nothing is written when nothing changed (no redundant file writes, no sync churn).
• The feature can be turned off with the "Save Form State into HTML File" toggle in the plugin settings (disabled by default).

Auto Reload On File Change

When the opened file is modified outside of the view — by an external editor, a script that regenerates it, or vault sync — the view reloads itself automatically, so what you see is never stale. The scroll position is preserved across the reload.

• Bursts of write events (external editors and sync often write a file in several steps) are coalesced into a single reload.
• Writes made by Form State Persistence are recognized by comparing the file content with what the plugin wrote last, so saving form state never triggers a reload — content comparison instead of timestamps makes this race-free.
• When a reload is triggered while a form state write is still pending, the pending write is dropped rather than flushed, so an external change is never overwritten by stale in-memory state.
• The feature can be turned off with the "Auto Reload On File Change" toggle in the plugin settings (enabled by default). Pressing F5 still reloads on demand.

How to build this plugin from source code

1. Clone this project to your system.
2. Under the local project folder, key the command npm i to install necessary packages.(You need Node.js installed on your development environment)
3. Then run npm run dev would build the plugin files.

Known issues

• Cannot see local image files like <img src="./image1.jpg" /> or <img src="file:///C:/image1.jpg" />

  • This is Obsidian's constraint, it disallow to directly access local files through HTML code.
  • One of the possible remedy ways is re-save the HTML file as a complete HTML file by dedicated browser extensions such as "SingleFile", it can save a complete page (with CSS, images, fonts, frames, etc.) as a single HTML file. After got the complete HTML file, put it to obsidian-html-plugin installed vault folder then open it, you would see all images.
  • Another remedy way is add app://local/ or app://local// prefix string to src attribute by hands(refer to "Allow embed of Local images using ![](file:///...)"). (USELESS)
  • From Obsidian v1.8+, it support some HTML tags with src relative paths for Markdown(.md) format documents. But it still disallowed to load any local resources for HTML(.html) documents.

• After some .html files were opened, they look like blank pages and cannot see original contents.

  • In fact, currently (after 1.0.13), this plugin can handle only some kinds of HTML files:
    1. Standard HTML5 files
    2. Compressed HTML-like files made by SingleFileZ
    3. MHTML format files (after enabled 'MHTML File Format Supported' setting, converting by mhtml-to-html)
  • Therefore, when open unsupported file format, this plugin would notice related messages or show an almost blank page.
  • "open document with .html and .htm file extensions" is the description written for end-users without technical background. It doesn't mean this plugin can open all kinds of files with .html or .htm file extensions, especially when the file actually is other document type but renamed to .html or .htm file extension.
  • If you want to open an ePub file, you shall install "ePub Reader" plugin to open it, instead rename it to xxx.html then ask why this plugin cannot open it.

• Some HTML elements disappeared

  • That might be caused by:
    1. Removed by HTML Sanitization mechanism
    2. Hide or become invisible
  • You could try to switch Operating Mode to different modes to see if the disappeared HTML elements become visibile. If YES, you could create a new issue in Issues page to let me know, and I will discuss it with you.
  • If you still cannot see the disappeared HTML elements after switching to less restricted modes, that means they were hide or became invisible. This situation often occurs when the HTML element use some advanced features like "Declarative Shadow DOM" (this feature has been supported after verion 1.0.4) and this plugin or Obsidian not supported yet. Then, you could create a new issue in Issues page to let me know, and I will discuss it with you.

• Almost all script codes cannot work

  • That might be caused by:
    1. Blocked by HTML loading procedure
    2. Removed by HTML Sanitization mechanism
  • Obsidian's developer team is very concern about XSS attacks, so they want plugin developers follow this tip to prevent XSS attacks. Therefore, almost all script codes resident inside <script> in the HTML file would be blocked, and the external script files are the same.
  • Meanwhile, HTML Sanitization mechanism would sanitize potential XSS code more deeper. So, the code such as <... onload="alert(1)"> would be removed.
  • Therefore, you could switch to less restricted modes to see if they work or not.

• Cannot zoom in or out by mouse wheel on mobile platforms

  • It seems the Obsidian app block something on mobile platforms, so these actions would not work normally.
  • You could use two-finger pinch-zoom gesture on the touch screen to zoom in or out.
  • You could use the "more options" menu items to zoom in or out.

• The zoom related hotkey settings are disappeared on mobile platforms

  • The mobile version of Obsidian does not provide these settings, so this plugin also not provide them.

• The presentation style of search results is different with Markdown documents

  • There are lots tags/elements inside HTML files, and some search results would across tags and overlap with each others. Therefore, this plugin use the block mark style (highlight with background color) instead of outline style.

• Cannot open some files in vault by <a> tags

  • It seems the Obsidian app block some kinds of hyperlinks, e.g.: <a href="file:///...">