# Comnto

> Comnto is a hosted comments widget for websites. One script (https://comnto.com/embed.js) mounts it in an iframe, configured by data-* attributes on a container or by calling window.comnto(options). These docs cover embedding, single sign-on, importing existing comments, appearance and localization, and the widget's JavaScript API.

Key facts:

- Every widget needs a site id: `data-site` on the container or `site` in `window.comnto()`. The page's hostname must be on the site's trusted domains list in the dashboard.
- A thread is identified by `data-topic` / `topic`. If omitted, one is derived from the page URL, but passing a stable id such as the article id is recommended.
- Embed options (theme, colours, locale, direction, custom CSS, SSO token) can be changed at runtime through the handle `window.comnto()` returns, without reloading the iframe.
- Editor tools (formatting, image and mention limits) are set only in the dashboard and enforced when a comment is saved; no embed option overrides them.
- SSO tokens are HMAC-SHA256 signed with the site's `sso_secret` and must be generated on the server.

## Table of Contents

### Getting Started

- [Comnto Comments Widget](https://docs.comnto.com/index.md): What the Comnto widget does and a quick start: add a data-comnto container with your site id and load embed.js, via data attributes or window.comnto().

### Integration

- [Integration Overview](https://docs.comnto.com/integration.md): The two ways to mount the widget (data attributes or window.comnto()), how the loader derives topics and sizes the iframe, and which method to choose.
- [Using Data Attributes](https://docs.comnto.com/integration/data-attributes.md): Every data-* attribute the embed script reads from a data-comnto container, including per-colour attributes, multiple widgets, and when to switch to the JavaScript API.
- [Using the `window.comnto()` API](https://docs.comnto.com/integration/window-api.md): Options accepted by window.comnto(options), mounting several widgets on one page, and re-rendering inside single page apps.
- [Importing Comments](https://docs.comnto.com/integration/comment-import.md): Importing existing comments from a Disqus XML export or a custom JSON file: topic and comment schema, allowed HTML, running the import, and fixing skipped comments.
- [Single Sign-On (SSO)](https://docs.comnto.com/integration/sso.md): Signing your users into the widget with an HMAC-SHA256 token built on your server: payload fields, Node/PHP/Python/Ruby/Go examples, delivery, refresh, and SSO-only mode.

### Customization

- [Customization](https://docs.comnto.com/customization.md): Overview of what can be customised (appearance, language and direction, editor tools) and whether it is set in the embed or the dashboard.
- [Appearance](https://docs.comnto.com/customization/appearance.md): Theme modes (auto/light/dark), brand colour tokens, sanitised custom CSS (16 KB cap), background detection hints, branding, and responsive sizing.
- [Localization & Direction](https://docs.comnto.com/customization/localization.md): Choosing one of 22 bundled locales, overriding UI phrases, forcing LTR/RTL direction, and handling multilingual pages.
- [Editor Tools](https://docs.comnto.com/customization/editor-tools.md): Dashboard-only settings for which formatting tools, how many images, and how many mentions the comment box allows; enforced when a comment is saved, with no embed override.

### Reference

- [Widget API](https://docs.comnto.com/reference/widget-api.md): Methods, properties, and events of the handle returned by window.comnto(): setLocale, setTheme, setColors, update, reload, on, destroy, with examples.

### Troubleshooting

- [Troubleshooting](https://docs.comnto.com/troubleshooting.md): Fixes for a widget that won't load (invalid site id, untrusted domain, CSP), wrong background colours, and overrides that don't apply.