- Overview
- Scorecard
- Updates15
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
- More Options
- How to build this plugin from source code
- Known issues
How to use
- Put .html or .htm files to any obsidian-html-plugin installed vault folder
- Click any HTML or HTM item to open it
- Reading
Install this plugin from Obsidian
- Head to ⚙"Settings" ⇨ "Community plugins" options page, make sure "Restricted mode" is turned off.
- Click
Browsebutton to open Community plugins browsing dialog. - Search for this plugin "HTML Reader" and click the corresponding result item.
- Click
Installbutton to install this plugin. - Once installed, click
Enablebutton to enable this plugin. - Or, enable this plugin "HTML Reader" from the "Installed plugins" list of "Community plugins" options page.
Manually installing the plugin
- Copy the
main.jsandmanifest.jsonfiles from Releases list to your vault<path>/<to>/<vaultFolder>/.obsidian/plugins/obsidian-html-plugin/. - Relaunch Obsidian.
- 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
- Head to ⚙"Settings" ⇨ "Community plugins" options page, find the settings icon ⚙ of "HTML Reader" item, then click it.
- 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
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.
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.
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.
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.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).
- 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 .
- 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.
- DSD - It means Declarative Shadow DOM.
- 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. - 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.
- 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
:targetpseudo-class event would never be fired. You can get more details from the CSS Isolation wiki page. - 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.
- 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.
- 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.
How to build this plugin from source code
- Clone this project to your system.
- Under the local project folder, key the command
npm ito install necessary packages.(You need Node.js installed on your development environment) - Then run
npm run devwould build the plugin files.
Known issues
Cannot see local image files like
<img src="https://raw.githubusercontent.com/nuthrash/obsidian-html-plugin/HEAD/image1.jpg" />or<img src="https://raw.githubusercontent.com/nuthrash/obsidian-html-plugin/HEAD/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(USELESS)app://local/orapp://local//prefix string tosrcattribute by hands(refer to "Allow embed of Local images using").- From Obsidian v1.8+, it support some HTML tags with
srcrelative 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:
- Standard HTML5 files
- Compressed HTML-like files made by SingleFileZ
- 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
.htmland.htmfile 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.
- In fact, currently (after 1.0.13), this plugin can handle only some kinds of HTML files:
Some HTML elements disappeared
- That might be caused by:
- Removed by HTML Sanitization mechanism
- 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.
- That might be caused by:
Almost all script codes cannot work
- That might be caused by:
- Blocked by HTML loading procedure
- 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.
- That might be caused by:
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:///...">
- It seems the Obsidian app block some kinds of hyperlinks, e.g.: