Adding Comments with Utterances

August 25, 2025

I wanted to add a lightweight way for people to interact with my Jekyll posts without running my own backend. Utterances turned out to be perfect: free, simple, and powered by GitHub Issues.

Setup Steps

  1. Create a repo just for blog comments (or reuse an existing one).
    • I made a public repo, separate from my sites private repo.
    • Installed the Utterances GitHub App on that repo.
  2. Generate the config on utteranc.es
    • Fill in your user/repo
    • Choose your mapping
      • I went with pathname so each post maps to a unique issue automatically. It seemed the best choice for my Jekyll generated site.
    • Add a label (optional)
    • Choose a Theme
    • Click copy and move to step 3.

  3. Add the embed
    I made an include file from the generated config plus added some noscript text because I’m old.

    <!-- _includes/comments-utterances.html -->
<div id="comments">
  <script src="https://utteranc.es/client.js"
          repo="USER/REPO"
          issue-term="pathname"
          label="blog-comments"
          theme="github-dark"
          crossorigin="anonymous"
          async>
  </script>
  <noscript>Please enable JavaScript to view the comments powered by Utterances.</noscript>
</div>

  4. Wire it into my layout
    In _layouts/post.html:

    ```liquid


5. **Toggle per post**  
   By default comments show up. If I don’t want them:

   ```yaml
   comments: false

Notes

  • Issues get auto-created in the repo on first comment.
  • Comments support Markdown + reactions.
  • Users need a GitHub account to comment, which should keep spam low.. and I imagine if I have any audience they probably use Github.
  • I used the ‘label’ setting just to try it out. I could use this to label comments based on the post type at some point.
  • You can customize the layout and theme.

That’s it. I finished the implementation in less than ten minutes. It seriously took me longer to write this page out. I imagine if I wanted to customize it a bit, that would add some time, but I just wanted to see how it worked.

Leave a comment below if this helped you I guess…

Update

I added a specific comment box for 404 pages so that bad links could be reported. Since the default method uses the pathname to generate each issue for comments, I needed to change issue-term="pathname" to issue-number="1". This ties is to issue number 1 on the github repo no matter the link it comes from.