Forem: Yoni Ryabinski

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

Yoni Ryabinski — Tue, 14 Apr 2026 13:23:26 +0000

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

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

How to Add Comments to a Hugo Site (Without a Backend)

Yoni Ryabinski — Fri, 10 Apr 2026 22:20:27 +0000

Hugo is wonderful for performance and terrible for anything stateful — including comments. If you want readers to talk back, you need a third-party widget that runs in the browser.

Here's the shortest path to threaded comments on a Hugo site, using EchoThread (privacy-first, no ads, no tracking, under 15 KB gzipped, free during beta).

1. Get an API key

2. Add the embed to `layouts/_default/single.html`

{{ define "main" }}
<article>
  <h1>{{ .Title }}</h1>
  {{ .Content }}
</article>

<section class="comments">
  <div id="echothread" data-api-key="{{ .Site.Params.echothreadApiKey }}"></div>
  <script src="https://cdn.echothread.io/widget.js" defer></script>
</section>
{{ end }}

3. Add the key to `hugo.toml`

[params]
  echothreadApiKey = "YOUR_API_KEY"

Or use an env var: HUGO_PARAMS_ECHOTHREADAPIKEY=... hugo. Hugo maps HUGO_PARAMS_* automatically.

4. (Optional) Make a shortcode

layouts/shortcodes/echothread.html:

<div class="echothread-wrapper">
  <div id="echothread" data-api-key="{{ .Site.Params.echothreadApiKey }}"></div>
  <script src="https://cdn.echothread.io/widget.js" defer></script>
</div>

Now you can drop {{< echothread >}} into any Markdown file.

5. Theme it

.comments {
  --echothread-bg: #0f0f10;
  --echothread-text: #e8e8ea;
  --echothread-accent: #7c5cff;
  min-height: 400px;
}

That min-height matters — it prevents layout shift when the widget hydrates.

Done

The widget identifies threads by page URL automatically, so every post gets its own conversation with no extra config. Sign in with Google to leave a comment, manage everything from the EchoThread dashboard.

Full guide with troubleshooting and CSP notes: echothread.io/docs/guides/hugo

How to Add Comments to an Astro Site (Lazy-Loaded, Zero JS by Default)

Yoni Ryabinski — Thu, 09 Apr 2026 20:38:55 +0000

Astro's "ship zero JavaScript by default" model is a perfect fit for comment widgets — they're the one thing on the page that actually needs to be interactive, and they're the perfect candidate for lazy loading.

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

1. Get an API key

2. Add the key to `.env`

PUBLIC_ECHOTHREAD_API_KEY=YOUR_API_KEY

The PUBLIC_ prefix is required to expose it client-side.

3. Create `src/components/EchoThread.astro`

---
const apiKey = import.meta.env.PUBLIC_ECHOTHREAD_API_KEY;
const { theme = "auto" } = Astro.props;
---

<section class="echothread-wrapper">
  <div id="echothread" data-api-key={apiKey} data-theme={theme}></div>
  <script src="https://cdn.echothread.io/widget.js" defer></script>
</section>

<style>
  .echothread-wrapper {
    margin-top: 4rem;
    padding-top: 2rem;
    border-top: 1px solid var(--border-color, #e5e5e5);
    min-height: 400px;
  }
</style>

4. Use it in your post layout

---
import BaseLayout from "./BaseLayout.astro";
import EchoThread from "../components/EchoThread.astro";
---
<BaseLayout title={frontmatter.title}>
  <article>
    <h1>{frontmatter.title}</h1>
    <slot />
  </article>
  <EchoThread />
</BaseLayout>

5. (Bonus) Lazy-load with IntersectionObserver

If you want true zero-JS until the reader actually scrolls to the comments:

<section id="echothread-section">
  <div id="echothread" data-api-key={apiKey}></div>
</section>

<script>
  const section = document.getElementById("echothread-section");
  const observer = new IntersectionObserver((entries) => {
    if (entries[0].isIntersecting) {
      const s = document.createElement("script");
      s.src = "https://cdn.echothread.io/widget.js";
      s.defer = true;
      document.body.appendChild(s);
      observer.disconnect();
    }
  }, { rootMargin: "200px" });
  observer.observe(section);
</script>

Now the widget script never loads for readers who don't scroll past the post.

Done

The widget identifies threads by page URL automatically. Works with content collections, MDX, static or SSR builds.

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

How to Add Comments to a Next.js Site (App Router and Pages Router)

Yoni Ryabinski — Thu, 09 Apr 2026 00:18:05 +0000

Next.js gives you so many ways to render a page that the answer to "how do I add comments" depends on which version you're on and which architecture you've chosen. Here's a single approach that works for both the App Router and the Pages Router: a small client component that wraps the EchoThread widget (privacy-first, no ads, under 15 KB gzipped, free during beta).

1. Get an API key

2. Add to `.env.local`

NEXT_PUBLIC_ECHOTHREAD_API_KEY=YOUR_API_KEY

The NEXT_PUBLIC_ prefix is mandatory for client-side access.

3. Create `components/EchoThread.tsx`

"use client";

import Script from "next/script";

export default function EchoThread({ theme = "auto" }: { theme?: string }) {
  const apiKey = process.env.NEXT_PUBLIC_ECHOTHREAD_API_KEY;
  if (!apiKey) return null;

  return (
    <section
      className="echothread-wrapper"
      style={{ marginTop: "4rem", paddingTop: "2rem", minHeight: 400 }}
    >
      <div id="echothread" data-api-key={apiKey} data-theme={theme}></div>
      <Script src="https://cdn.echothread.io/widget.js" strategy="lazyOnload" />
    </section>
  );
}

The lazyOnload strategy ensures the widget never blocks LCP.

4. Use it in your post page

App Router (app/blog/[slug]/page.tsx):

import EchoThread from "@/components/EchoThread";

export default async function Post({ params }) {
  const post = await getPost(params.slug);
  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
      <EchoThread />
    </article>
  );
}

Pages Router is essentially identical — same component, just imported into your pages/blog/[slug].tsx.

5. Handle soft navigation

Next.js does client-side navigation between routes. To make sure the widget refreshes when readers click between posts, force a remount with a key prop:

"use client";
import { usePathname } from "next/navigation";
import EchoThread from "@/components/EchoThread";

export default function Wrapper() {
  const pathname = usePathname();
  return <EchoThread key={pathname} />;
}

For Pages Router, use useRouter().asPath instead.

Done

The widget identifies threads by page URL automatically. Server components stay server components — only the comment island hydrates.

Full guide with troubleshooting and CSP notes: echothread.io/docs/guides/nextjs

Forem: Yoni Ryabinski

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

1. Get an API key

2. Set up env var loading

3. Add a shortcode in .eleventy.js

4. Use it in your post layout

5. Make it opt-in (optional)

6. Theme it

Done

How to Add Comments to a Hugo Site (Without a Backend)

1. Get an API key

2. Add the embed to layouts/_default/single.html

3. Add the key to hugo.toml

4. (Optional) Make a shortcode

5. Theme it

Done

How to Add Comments to an Astro Site (Lazy-Loaded, Zero JS by Default)

1. Get an API key

2. Add the key to .env

3. Create src/components/EchoThread.astro

4. Use it in your post layout

5. (Bonus) Lazy-load with IntersectionObserver

Done

How to Add Comments to a Next.js Site (App Router and Pages Router)

1. Get an API key

2. Add to .env.local

3. Create components/EchoThread.tsx

4. Use it in your post page

5. Handle soft navigation

Done

3. Add a shortcode in `.eleventy.js`

2. Add the embed to `layouts/_default/single.html`

3. Add the key to `hugo.toml`

2. Add the key to `.env`

3. Create `src/components/EchoThread.astro`

2. Add to `.env.local`

3. Create `components/EchoThread.tsx`