How to add comments to a Publii site with the official EchoThread plugin

Publii builds a static site on your computer and uploads plain HTML, so there is no server to run a comment form against. Comments on a Publii site are always a hosted service loaded in the browser. Since 20 August 2026 the Publii team ships an official EchoThread plugin in their marketplace, which means the setup is now a plugin switch and one API key instead of a snippet pasted into a theme file.

This guide walks through the whole thing, then covers the settings worth changing and the handful of problems people hit.

What you get

• Threaded replies, reactions, image attachments and link previews, in a widget that is under 60 KB gzipped and loads asynchronously, so your Publii site stays as fast as it is now.
• Readers can comment as a guest without creating an account, or sign in with a passkey, Google, GitHub, X or Facebook. You choose per site.
• Every comment, guest or signed-in, is scored by a machine-learning spam filter before it goes live. Fluent AI-written spam is what it was built for, and you never approve comments one by one unless you want to.
• No ads and no third-party tracking on any plan, including the free one. Publii's own plugin page notes this, and it matters if your site runs a cookie banner: the plugin can hold the widget until the visitor consents.
• Structured data for approved discussions (schema.org DiscussionForumPosting), so search engines and answer engines can read the comments instead of skipping a JavaScript block.

EchoThread's Hobby plan is free for your first site: unlimited comments, no ads, no reader tracking, and 10,000 page views a month on sites created from 1 October 2026 (a site created before that date keeps unmetered page views). Paid plans start at $9 a month for three sites and 100,000 page views; see pricing for the full ladder.

Before you start

• Publii 0.46 or newer. The plugin is version 1.0.0 (released 19 August 2026) and lists 0.46.x as the minimum.
• An EchoThread account. Create one free if you do not have one.
• The domain your Publii site publishes to. EchoThread ties each site to a registered domain, and the widget only loads on that domain (plus localhost for testing).

Step 1: install the plugin

1. In Publii, open the app menu (the three dots, top right) and choose Plugins.
2. Click Get More Plugins. That opens the Publii Plugins Marketplace in your browser.
3. Find EchoThread and click Download.
4. Back in Publii's Plugins screen, click Install Plugin and pick the file you just downloaded.

Publii installs it and lists it. Installation is app-wide; enabling it is per site, which is the next step.

Step 2: get your API key

1. Open the EchoThread dashboard and add a site.
2. Enter the domain your Publii site publishes to, exactly as visitors will see it.
3. Open the site's settings and copy the API key.

Copy the bare key. Publii's documentation is explicit about this: paste it without quotation marks and without the surrounding embed code. The plugin builds the embed itself.

Step 3: enable the plugin and paste the key

1. Open Tools & Plugins for the site.
2. Find EchoThread Comments and turn its switch on (it goes from grey to blue).
3. Click the plugin card, paste the API key into the API key field, and save.

The defaults are sensible. The one thing to decide now is the comments language: leave it on browser detection and the widget follows each visitor (English, Italian, Korean and Simplified Chinese today), or pin it to one language.

Step 4: make sure your theme shows comments

Publii themes control whether a post page has a comment area at all. Go to Theme, then Custom Settings, then Post/Page Options, and enable Display Comments.

Current Publii themes already support plugin comments. If you are on an older or hand-made theme and nothing appears, the theme is missing the helper the plugin renders into. Open Documents/Publii/sites/YOUR_SITE/input/themes/YOUR_THEME/post.hbs and replace the old comments block with:

{{#if @config.post.displayComments}}
    <div class="post__comments">
        <div class="wrapper">
            {{{@commentsCustomCode}}}
        </div>
    </div>
{{/if}}

Step 5: regenerate and sync

Any change to plugin settings needs a regenerate. Sync the site as usual, open a post on the real domain, and the comment section is there.

One thing that catches everyone: the plugin does not load the live widget inside Publii's Preview. Preview runs on a local address that is not your registered domain, so you will see the fallback message there. Test on the published site or on a registered staging domain.

How the plugin keeps threads attached to the right post

The plugin gives every post and page a stable thread identifier from its Publii content ID, for example post-54 or page-63. If you rename a post or change its slug, the discussion stays attached, because the ID did not change. If you delete a post and recreate it, it gets a new ID and a new, empty thread. That is the only way to lose a thread by accident.

For the page URL, the plugin reads Publii's @website.pageUrl. With absolute URLs it sends the full address; with relative URLs it leaves the attribute out and the widget reads the public address from the visitor's browser. Either way works.

Settings worth a second look

• Color theme: follow the visitor's system setting, force light or dark, set a background colour, or point it at a CSS custom property like --color-bg so the widget follows your theme's dark mode automatically.
• Accent color, widget font, base font size (default 14) and corner radius (default 8) get the widget matching your theme without CSS.
• Load comments when visible is on by default: the script only loads when the reader scrolls near the comment section. Turn it off if you want comments visible in the first paint.
• Add discussion structured data is on by default. Turn it off only if you already render discussion JSON-LD yourself, or you will emit it twice.
• Require consent before loading is for sites with the Publii Cookie Banner. Go to Site Settings, then Privacy Settings, enable the banner's advanced configuration, add EchoThread to a group (for example "functionality") with a Group ID such as comments, and enter the identical Group ID in the plugin. An empty or mismatched Group ID keeps the widget blocked, because the plugin cannot tell which consent unlocks it.

Troubleshooting

Moving from Disqus, Cusdis or Commento

If your Publii site already had comments elsewhere, bring them with you before you switch the plugin on. Disqus exports an XML file that EchoThread imports in one step, matching old threads to page URLs; the Disqus export and migration guide covers it. Cusdis was deprecated in July 2026 and Publii removed its plugin; its maintainers will send you an export by email, and the Cusdis alternative guide explains how to bring that data in.

For a broader look at what is left in Publii's marketplace after the August 2026 clean-up, read Disqus alternatives for Publii.