How to Add Comments to an Eleventy Site (with a Custom Shortcode)

Eleventy gets out of your way, which is great until you want a feature like comments and have to wire it up yourself. The cleanest answer: a hosted widget plus a custom shortcode so you can drop comments into any template with one line.

Here's how to add EchoThread (privacy-first, no ads, under 15 KB gzipped, free during beta) to an Eleventy site.

1. Get an API key

Sign up at echothread.io, add your domain, copy the key.

2. Set up env var loading

Install dotenv:

npm install --save-dev dotenv

.env:

ECHOTHREAD_API_KEY=YOUR_API_KEY

3. Add a shortcode in .eleventy.js

require("dotenv").config();

module.exports = function (eleventyConfig) {
  eleventyConfig.addShortcode("echothread", function () {
    const apiKey = process.env.ECHOTHREAD_API_KEY;
    if (!apiKey) return `<!-- EchoThread: missing key -->`;
    return `
<section class="echothread-wrapper">
  <div id="echothread" data-api-key="${apiKey}"></div>
  <script src="https://cdn.echothread.io/widget.js" defer></script>
</section>`;
  });

  return { dir: { input: "src", output: "_site" } };
};

4. Use it in your post layout

---
layout: layouts/base.njk
---
<article>
  <h1>{{ title }}</h1>
  {{ content | safe }}
  {% echothread %}
</article>

5. Make it opt-in (optional)

Add comments: true to a post's front matter, then:

{% if comments %}
  {% echothread %}
{% endif %}

6. Theme it

.echothread-wrapper {
  --echothread-bg: #fafafa;
  --echothread-text: #1a1a1a;
  --echothread-accent: #2563eb;
  min-height: 400px;
}

Done

The widget identifies threads by page URL automatically. Every post gets its own conversation, no extra config. Eleventy stays essentially zero-JS aside from the widget itself.

Full guide with troubleshooting: echothread.io/docs/guides/eleventy