Html Viewer

View static HTML files directly in Nextcloud

HTML files can be a great way to illustrate content in an interactive and responsive format. The HTML viewer app enables viewing and editing of static HTML files directly within Nextcloud.

Security information

Loading HTML files within the context of Nextcloud carries a risk of exposing user information to third parties, depending on the configuration of the server. The HTML viewer app uses the sandbox and CSP features for iframes to disable JavaScript and prevent access to user information and websites outside your Nextcloud, but this can not guarantee that no information is ever transferred to third parties.

Administrators should also be aware that some users may not be able to differentiate between the content of an HTML file they have opened and the normal user interface of Nextcloud.

Support

• Matrix Chat

Settings

All settings can be changed in the administration settings under "Additional settings" → "HTML Viewer" or with the occ commands below. Every setting can be reset to its default there. An empty CSP or sandbox restores the default policy.

Enable Links

By default, links in the HTML files can only be opened with CRTL+click. Links with the target="_blank" attribute can be enabled by setting a custom sandbox value that includes the permission allow-popups. Otherwise, the "newTabLinks" feature can be enabled to set the permissions automatically and convert any links without target="_blank" to include it.

./occ config:app:set htmlviewer newTabLinks --value=true --type=boolean

Enable JavaScript

JavaScript for HTML files is disabled by default. Enabling it is a bad idea and we do not recommend this at all. Although security features like sandboxing, CSP and CORS limit what can be done, it still means that unknown code is being executed within Nextcloud.

If you still wish to enable JS, this occ command will enable it:

./occ config:app:set htmlviewer allowJs --value=true --type=boolean

Note: If you set a custom CSP or Sandbox value, this feature may not work if your CSP/Sandbox values do not allow JS execution. However, you must still enable this feature if you use a custom CSO/Sandbox if you want to allow JS. As of Nextcloud 34, eval() and similar methods are no longer supported by Nextcloud and can't be enabled.

Set File Size Limit

By default, the app will load HTML files up to 32MB. To change the file size, use this occ command:

./occ config:app:set htmlviewer maxSize --value=SizeInMegabyte

Set Editor Size Limits

By default, files up to 16MB can be edited and files up to 5MB are edited in a code editor with syntax highlighting while larger files are shown in a plain text field. The editor limit can't exceed maxSize and the code editor limit can't exceed the editor limit. To change the limits, use these occ commands:

./occ config:app:set htmlviewer maxEditorSize --value=SizeInMegabyte --type=integer
./occ config:app:set htmlviewer maxCodeEditorSize --value=SizeInMegabyte --type=integer

Direct Editing in the Mobile and Desktop Apps

The app offers itself as editor for HTML files to the Nextcloud Android and desktop apps through the direct editing API. The Nextcloud Text app also offers to edit HTML files, but the clients use the HTML viewer when both apps are installed. The Nextcloud iOS app only supports a fixed list of editors and keeps using Text. To leave the direct editing of HTML files to the Text app, use this occ command:

./occ config:app:set htmlviewer directEditing --value=false --type=boolean

Change CSP and Iframe Permissions

The app automatically configures the iframe with an CSP for supported browsers and a sandbox to limit code execution and data access. Both policies can be changed through config settings with the OCC commands shown below. Please be aware that the general CSP of your Nextcloud may still block some access regardless of what CSP and sandbox settings you configure.

To change the CSP or sandbox settings, use these occ commands:

./occ config:app:set htmlviewer csp --value=YourCustomCSP
./occ config:app:set htmlviewer sandbox --value=YourCustomSandbox

Documentation of CSP directives. Documentation of Sandbox permissions.

Translations

The translations are maintained as gettext files in translations/. Messages use language keys as msgid, the English texts are defined in translations/en.po. The Nextcloud translation files in l10n/ are created from the PO files during the build and should not be edited. Missing translations fall back to the English text.

To add a new text, add the key to translations/en.po, use it with the t() helper from src/utils/l10n.js and update the other PO files:

npm run l10n:sync

To add a new language, create an empty translations/<language>.po with the PO header and run npm run l10n:sync.