> ## Content Index > Fetch the complete content index at: https://getpublii.com/docs/llms.txt > Use this file to discover other available public pages before exploring further. # EchoThread Plugin - URL: https://getpublii.com/docs/echothread-plugin.html - Published: 2026-08-19T03:02:44.868Z - Updated: 2026-08-19T16:42:48.374Z - Description: Add EchoThread comments to Publii posts and pages. Configure the API key, themes, structured data, lazy loading, Cookie Banner consent, and troubleshooting. - Author: Publii Team - Tags: plugins [EchoThread](https://echothread.io/) is a hosted comment platform with threaded replies, reactions, image attachments, and machine-learning spam filtering. The EchoThread Comments plugin adds its widget to selected posts and pages on your Publii site. You need an EchoThread account, a registered domain, and the API key assigned to that site. The plugin connects each Publii post or page to a stable EchoThread thread identifier, so changing a slug does not separate an existing discussion from its content. ## Adding Comment Plugin Support to Older or Custom Themes Current Publii themes include support for comment plugins. Follow this section only if you use an older theme or a custom theme that does not include the `commentsCustomCode` helper. 1. Open your file manager and go to `Documents/Publii/sites/YOUR_SITE/input/themes/YOUR_THEME`. Replace `YOUR_SITE` with your site's folder name and `YOUR_THEME` with the active theme's folder name. 2. Open the theme's `post.hbs` file in a code editor. Update other post templates and the page template if they contain separate comment blocks. 3. Near the end of the file, find the old comments block. It may look like this: ```html {{#if @config.post.displayComments}}

{{ translate 'post.comments' }}

{{> disqus}}
{{/if}} ``` Replace it with: ```html {{#if @config.post.displayComments}}
{{{@commentsCustomCode}}}
{{/if}} ``` 4. Save the file. Keep a backup of custom theme changes. A theme update can replace edited theme files. ## Activating the Plugin 1. Open **Tools & Plugins** in Publii. 2. Find **EchoThread Comments** and enable its switch. 3. Click the plugin card to open its options. 4. Enter your **API key**, review the display settings, and save the changes. 5. Regenerate the website after changing the plugin configuration. ## Creating an EchoThread Site and Finding the API Key The API key connects the widget to the domain, threads, comments, and moderation settings stored in your EchoThread account. 1. Create an account through the [EchoThread registration page](https://echothread.io/register), or sign in to an existing account. 2. Open the [EchoThread dashboard](https://echothread.io/dashboard) and add a site. 3. Enter the domain where you will publish the Publii website. EchoThread uses this domain to validate widget requests. 4. Open the site's settings and copy its API key. 5. Paste the key into the plugin's **API key** field. Copy the key without quotation marks or the surrounding embed code. Publii creates the EchoThread container and script loader. You do not need to paste the EchoThread embed snippet into your theme. **Plan information:** **The EchoThread Hobby plan is free for your first site** and includes monthly usage limits. Check the [current EchoThread pricing and limits](https://echothread.io/pricing) before publishing. ## Enabling Comments in Your Theme The plugin supplies the EchoThread widget. Your theme decides where Publii can display it. To enable comments for posts or pages across the site, open **Theme** and go to **Custom Settings** → **Post Options** or **Page Options**. Enable **Display Comments**. You can also control comments for one post or page. Open the item in the editor, click the settings icon, choose **Other Options**, and change **Display Comments**. ## EchoThread Comments Plugin Options The plugin settings control the EchoThread connection, interface language, structured data, appearance, loading behavior, and Cookie Banner integration. **Required:** Enter a valid **API key** and register the published domain in EchoThread. The service rejects widget requests from domains that do not match the site settings. ### Comments Configuration - **API key** – The key assigned to the registered site in the EchoThread dashboard. - **Comments language** – Lets EchoThread follow each visitor's browser language or pins the interface to English, Italian, Korean, or Simplified Chinese. Browser mode falls back to English when EchoThread does not support the visitor's language. - **Add discussion structured data** – Lets EchoThread add schema.org `DiscussionForumPosting` JSON-LD for approved comments. Keep this option enabled unless your site renders the same EchoThread document on the server. ### Appearance - **Comments heading** – Text shown above the comment widget. Leave the field empty to hide the heading. - **Heading level** – The HTML heading level used for the title. **H2** suits most themes, but you can choose **H3** through **H6** to match the page structure. - **Color theme** – Follows the visitor's system setting, forces light or dark mode, uses a custom background color, or reads a CSS custom property from the site theme. - **Widget background color** – Sets a hexadecimal background when **Custom background color** is selected. EchoThread derives readable text and surface colors from this value. - **Theme CSS custom property** – Names the CSS custom property that stores the site's background color, for example `--color-bg`. EchoThread reads this value when **Theme CSS custom property** is selected. - **Accent color** – Sets the color used for the send button, links, and active controls. - **Sign-in button style** – Uses buttons with provider labels or compact icon-only buttons. EchoThread keeps accessible provider labels on the icon-only option. - **Widget font** – Selects the system, sans serif, serif, monospace, or rounded EchoThread preset. You can also inherit the site font or enter a custom font family. - **Custom font family** – Accepts a CSS `font-family` value such as `'Inter', sans-serif`. Your site must load the requested font files. - **Base font size** – Sets the widget font size from 10 to 32 pixels. The default is 14 pixels. - **Corner radius** – Sets the corner radius for the widget and comment cards from 0 to 40 pixels. The default is 8 pixels. - **Mobile composer gap** – Sets the space between the avatar and composer on screens up to 480 pixels wide. Enter a value from 0 to 32 pixels. The default is 6 pixels. - **Mobile avatar size** – Sets the avatar size on screens up to 480 pixels wide. Enter a value from 20 to 64 pixels. The default is 28 pixels. - **Mobile minimum width** – Keeps the automatic widget width or makes the widget fill the available host column on narrow screens. ### Messages - **JavaScript disabled message** – Text shown when a visitor has disabled JavaScript in the browser. ### Advanced Styling These fields change the Publii elements around the widget. Keep their default values unless your theme requires other CSS classes. - **Outer container CSS class** – Sets the class on the outer element surrounding the comments section. The default value is **comments**. - **Inner container CSS class** – Sets the class on the inner comment container. The default value is **comments-wrapper**. - **Heading CSS class** – Adds a CSS class to the comments heading. Leave the field empty to use the theme's standard heading style. Use the plugin's supported appearance fields instead of overriding EchoThread's internal interface rules with host-page CSS. The [EchoThread theming documentation](https://echothread.io/docs/#theming) lists the related embed attributes and CSS custom properties. ### Loading - **Load comments when visible** – Delays the EchoThread script until the visitor scrolls near the comment section. Disable the option when you want the widget to start loading with the page. ### Cookie Banner Integration - **Require consent before loading** – Prevents the browser from downloading the EchoThread script until the visitor accepts the selected Publii Cookie Group. - **Cookie Group ID** – The internal Group ID configured in **Site Settings** → **Privacy Settings** → **Cookie Groups**. Enter the same value in both places, for example **comments**. - **Message before consent** – Text shown where the EchoThread widget would appear until the visitor accepts the selected Cookie Group. ## Configuring Cookie Consent EchoThread states that it serves no ads and uses no third-party tracking. The service uses first-party state for account and comment functions. Your privacy policy and legal requirements determine whether you need consent before loading the external widget. Follow these steps if you enable **Require consent before loading** in the plugin: 1. Open **Site Settings** → **Privacy Settings**. 2. Enable the Cookie Banner and its advanced cookie configuration. 3. Add EchoThread to a suitable group, such as a functionality or comments group. 4. Give that group a Group ID, for example `comments`. Use letters, numbers, hyphens, or underscores without spaces. 5. Return to the EchoThread Comments plugin and enter the exact same value in **Cookie Group ID**. 6. Save the settings and regenerate the website. Keep **Cookie Group ID** filled while consent integration remains enabled. An empty or invalid value keeps EchoThread blocked because the plugin cannot determine which consent should unlock the script. Read [Publii's Cookie Banner guide](https://getpublii.com/docs/gdpr-cookie-banner-configuration.html#doesyoursiteuseanyexternalscripts) for details about external scripts and Cookie Groups. ## Thread Identity and URL Changes EchoThread uses the page URL to group comments when an embed does not provide a separate identifier. A renamed slug can then open a new discussion. The plugin assigns a stable value from the Publii content ID, such as `post-54` or `page-63`. Keep the same Publii content ID and EchoThread site to preserve the connection with its discussion. A custom EchoThread integration that used another identifier can create a separate thread. Plan a migration before replacing an existing custom embed with this plugin. ## Absolute and Relative Publii URLs The plugin reads the current address from Publii's `@website.pageUrl` data during rendering. It sends the full public page address when Publii generates an absolute `http://` or `https://` URL. Publii can also generate relative addresses such as `../../blog/article/`. In relative URL mode, the plugin omits the EchoThread page URL attribute and lets the widget read the final public address from the visitor's browser. The stable Publii content identifier remains unchanged. The plugin also sends the post or page title to EchoThread. EchoThread displays this title in the dashboard and notifications associated with the thread. ## Discussion Structured Data EchoThread can inject a schema.org `DiscussionForumPosting` JSON-LD document after it loads approved comments. The document includes approved comments and helps crawlers that execute JavaScript understand the discussion. Keep **Add discussion structured data** enabled for the standard client-side integration. Disable it only when your site fetches EchoThread's discussion JSON-LD on the server and writes that document into the original HTML. Rendering both copies can create duplicate structured data for the same thread. See the [EchoThread structured data documentation](https://echothread.io/docs/#structured-data) for the server-side endpoint and duplicate-data guidance. ## Language Settings Select **Follow visitor's browser** when each reader should see the widget interface in a supported browser language. EchoThread supports English, Italian, Korean, and Simplified Chinese and falls back to English for other browser languages. Select a specific language when you want all visitors to see one widget language. EchoThread translates interface text and dates. It does not translate the text written by commenters. ## Privacy Disclosure EchoThread processes comment content, account details, and moderation data as an external service. Review the [EchoThread Privacy Policy](https://echothread.io/privacy) and add the required information to your own privacy notice. Your disclosure should match the features enabled in the EchoThread dashboard, including guest comments, social sign-in, image uploads, and notifications. ## Preview Mode The plugin does not load the live EchoThread widget in Publii Preview. It displays a status message in its place. EchoThread validates requests against the domain registered for the API key, while a local Publii preview uses a different address. Generate or synchronize the site and open it from a registered staging or public domain to test comments, language, appearance, structured data, and the Cookie Banner flow. ## Troubleshooting - **No comment section appears** – Confirm that the plugin is enabled, the API key is present, and **Display Comments** is enabled for the current content type or item. - **EchoThread rejects the request** – Open the site settings in EchoThread and confirm that the registered domain matches the address used to open the generated website. - **The API key is rejected** – Copy the current key from the EchoThread site settings without quotation marks, spaces, or the surrounding HTML code. Regenerate the Publii site after replacing the key. - **Comments do not appear in Publii Preview** – Test the generated site on a registered staging or public domain. The plugin skips the external EchoThread request in Preview. - **A page shows a new empty discussion** – Check whether the Publii post or page ID changed, or whether an older custom integration used another EchoThread identifier. - **The widget starts loading only after scrolling** – Disable **Load comments when visible** when you want Publii to request EchoThread as the page loads. - **The selected color has no effect** – Choose a valid three-digit or six-digit hexadecimal color. - **The theme CSS custom property has no effect** – Confirm that the property starts with two hyphens, exists on the page, and contains a valid color, for example `--color-bg`. - **The custom font does not appear** – Confirm that the site loads the font files and that the **Custom font family** value uses valid CSS syntax. - **The interface uses the wrong language** – Select a fixed language in the plugin or check the visitor's browser language when browser mode is active. - **The consent message remains visible** – Confirm that the Cookie Group ID in the plugin matches the Group ID in Privacy Settings, including capitalization. - **Discussion structured data is missing** – Confirm that the option is enabled and that the thread contains approved comments. The standard EchoThread document appears after the widget runs in the browser. - **The page contains duplicate discussion structured data** – Disable the plugin option when your site already renders EchoThread's JSON-LD on the server. For current service behavior, see the official EchoThread guides to [widget configuration](https://echothread.io/docs/#configuration), [theming](https://echothread.io/docs/#theming), [moderation](https://echothread.io/docs/#moderation), [comment import](https://echothread.io/docs/#importing-comments), and [data export](https://echothread.io/docs/#exporting-comments).