How to add comments to a Jekyll site
Add a privacy-first comment system to your Jekyll blog or GitHub Pages site. No plugins or gems required — just a Liquid include and two lines of HTML.
On this page
Why Jekyll + EchoThread
Jekyll is the most popular static site generator for blogs, powering millions of sites on GitHub Pages. But static means no backend — so most Jekyll users either skip comments or add a heavyweight service that undermines their site's simplicity.
EchoThread gives you a full-featured comment system in two lines of HTML. No gems, no plugins, no build dependencies. It loads from a CDN at under 20 KB gzipped, works with GitHub Pages out of the box, and never shows ads or tracks your readers.
Prerequisites
- A Jekyll site (any version)
- An EchoThread account — create one free
- Your site's API key from the EchoThread dashboard
Step 1 — Create the include
Create a new file at _includes/echothread.html:
<div id="echothread"
data-api-key="YOUR_API_KEY"
data-page-url="{{ page.url | absolute_url }}"
data-identifier="{{ page.id | default: page.url }}"
data-page-title="{{ page.title | xml_escape }}"></div>
<script src="https://cdn.echothread.io/widget.js" async></script>
Step 2 — Add to your layout
Open your post layout at _layouts/post.html (create it if it doesn't exist) and add the include after the content:
---
layout: default
---
<article>
<h1>{{ page.title }}</h1>
{{ content }}
<!-- Comments -->
{% include echothread.html %}
</article>
Comments will now appear on every post.
Choosing an identifier
The data-identifier ties comments to a specific page. If you restructure your URLs later, the identifier keeps comments attached.
Jekyll provides these variables:
{{ page.id }}— the post's unique ID based on its date and slug, e.g./2026/04/07/my-post. Only available for posts, not pages.{{ page.url }}— the page's URL path, e.g./blog/my-post/. Works for both posts and pages.{{ page.slug }}— just the filename slug, e.g.my-post.
{{ page.id | default: page.url }} works well for most sites. It uses the post ID when available (stable across URL changes) and falls back to the URL for regular pages.
Theming
By default, EchoThread follows the visitor's OS light/dark preference. Override it with data-theme:
<!-- Force light mode -->
data-theme="light"
<!-- Custom background color -->
data-theme="#1a1a2e"
<!-- Custom accent color -->
data-accent-color="#e63946"
_config.yml using {{ site.echothread_theme }} to centralize your theming config.
Per-post control
Wrap the include with a Liquid conditional to allow disabling comments via front matter:
{% unless page.comments == false %}
<div id="echothread"
data-api-key="YOUR_API_KEY"
data-page-url="{{ page.url | absolute_url }}"
data-identifier="{{ page.id | default: page.url }}"
data-page-title="{{ page.title | xml_escape }}"></div>
<script src="https://cdn.echothread.io/widget.js" async></script>
{% endunless %}
Then in any post:
---
title: "About Me"
comments: false
---
GitHub Pages
EchoThread works on GitHub Pages with zero extra configuration. Since the widget loads from our CDN, there's no need for custom plugins or approved gems.
Things to note:
- GitHub Pages uses
jekyll buildunder the hood — your include file is processed normally. - Set your site domain in EchoThread to match your GitHub Pages URL (e.g.
username.github.ioor your custom domain). - For local development, also add
localhostas an allowed domain in your EchoThread site settings.
Collections
If you use Jekyll collections (e.g. _docs, _projects), the same include works. Collection items have a page.id just like posts:
---
layout: default
---
<article>
{{ content }}
{% include echothread.html %}
</article>
Troubleshooting
Comments don't appear
- Verify your API key is correct in the dashboard.
- Check that your site's domain matches (including
localhostfor development). - Look for JavaScript errors in the browser console.
Liquid syntax errors
If you see errors like Liquid Exception, make sure you're using the correct Liquid delimiters. The include file uses {{ }} for output and {% %} for logic.
Widget doesn't match my theme
Use data-theme with a hex color matching your site's background. For full control, override CSS custom properties. See the theming docs.
Ready to add comments to your Jekyll site?
Free during beta. Set up in under 5 min.
Create free account