How to Set Up Blog Comments Using Utterances

Have you ever wanted an easy, clean, and open-source way to add comments to your blog? That's exactly what I’ve done on my blog at shujaurrahman.comblogs, and I’ll walk you through how you can do it too using Utterances.

Utterances is a lightweight commenting system that uses GitHub Issues to store and manage comments. It’s secure, developer-friendly, and requires minimal setup. In this tutorial, I’ll guide you step-by-step to integrate Utterances into your blog so your readers can share their thoughts seamlessly.

Why Utterances?

1. Comment Storage: All comments are stored in a GitHub repository as issues.
2. Easy Discussions: Each blog post gets its dedicated issue for focused conversations.
3. Effortless Integration: Just a small script, and you’re done!
4. Secure and Open: No additional databases or third-party services required.

How It Works

1. Linking Comments:
   Each blog post links to a GitHub issue in your repository. The connection is based on something unique, like the post’s title and date.

2. Utterances Integration:
   When someone comments, their input is saved as a comment in the corresponding GitHub issue.

3. Discussion Management:
   You can respond to comments, manage discussions, or even label them—all through GitHub Issues!

What You’ll Need

• A blog or website (static or dynamic).
• A GitHub account.
• A GitHub repository to store your blog comments.

Step-by-Step Setup

Let’s dive into how to add Utterances to your blog.

1. Create a GitHub Repository for Comments

• Go to GitHub and create a new repository (I named mine blog-comments).
• This repository will store all the comments for your blog posts.
• Make it public—Utterances requires a public repository to work.

2. Install Utterances

• Visit the Utterances GitHub page.
• Scroll down and click Install Utterances.
• Scroll down to Install Utterances and select your new repository (blog-comments).

3. Configure Utterances in Your Blog

Add the following code snippet to your blog’s template where you want the comment section to appear:

<script src="https://utteranc.es/client.js"
        repo="shujaurrahman/blog-comments"
        issue-term="date.title" 
        theme="github-light"
        crossorigin="anonymous"
        async>
</script>

• src="https://utteranc.es/client.js": Loads the Utterances client script.
• repo="shujaurrahman/blog-comments": Replace shujaurrahman/blog-comments with the name of your GitHub repository.
• issue-term="title": Determines how each post is linked to an issue. Options include:
  • title: Links issues by the post’s title.
  • url: Links issues by the post’s full URL.
  • pathname: Links issues by the URL path.
  • I use date.title: Combines the post’s title and date for uniqueness.
• theme="github-light": Choose a theme for the comment widget (github-light, github-dark, etc.).
• async: Ensures the script doesn’t block page loading.

If your website has a theme toggle functionality, you can dynamically change the theme of Utterances based on the selected theme stored in local storage. Here's how you can do it:

4. Add Theme Toggle Functionality

To match your blog’s style, Utterances supports multiple themes. Simply change theme="github-light" to one of the following:

• github-dark
• preferred-color-scheme
• icy-dark
• dark-blue
• photon-dark

Add a Theme Toggle Button

<button id="theme-toggle-button">Toggle Theme</button>

JavaScript for Theme Toggle

<script>
    // Add an event listener to the theme toggle button
    document.getElementById('theme-toggle-button').addEventListener('click', function() {
        // Get the current theme from local storage
        const currentTheme = localStorage.getItem('selected-theme');
        // Determine the new theme
        const newTheme = currentTheme === 'dark' ? 'light' : 'dark';
        // Save the new theme in local storage
        localStorage.setItem('selected-theme', newTheme);
        // Update the data-theme attribute on the document element
        document.documentElement.setAttribute('data-theme', newTheme);
        // Reload the Utterances script with the new theme
        loadUtterances();
    });

    // Set the initial theme based on local storage
    const savedTheme = localStorage.getItem('selected-theme') || 'light';
    document.documentElement.setAttribute('data-theme', savedTheme);

    // Function to load the Utterances script with the appropriate theme
    function loadUtterances() {
        // Determine the theme for Utterances based on local storage
        const theme = localStorage.getItem('selected-theme') === 'dark' ? 'github-dark' : 'github-light';
        // Create a new script element for Utterances
        const script = document.createElement('script');
        script.src = 'https://utteranc.es/client.js';
        script.setAttribute('repo', 'shujaurrahman/blog-comments');
        script.setAttribute('issue-term', 'pathname');
        script.setAttribute('label', 'comment');
        script.setAttribute('theme', theme);
        script.crossOrigin = 'anonymous';
        script.async = true;
        // Get the discussion container element
        const discussionContainer = document.getElementById('discussion-container');
        // Clear any previous Utterances script
        discussionContainer.innerHTML = '';
        // Append the new Utterances script
        discussionContainer.appendChild(script);
    }

    // Load Utterances when the DOM content is fully loaded
    document.addEventListener('DOMContentLoaded', function() {
        loadUtterances();

        // Listen for changes in local storage
        window.addEventListener('storage', function(event) {
            if (event.key === 'selected-theme') {
                loadUtterances();
            }
        });
    });
</script>

Explanation

• Theme Toggle Button: The button with the ID theme-toggle-button is used to toggle the theme between light and dark.
• Event Listener for Theme Toggle: An event listener is added to the theme toggle button. When the button is clicked, the current theme is retrieved from local storage, and the new theme is determined and saved back to local storage. The data-theme attribute on the document element is updated, and the loadUtterances function is called to reload the Utterances script with the new theme.
• Set Initial Theme: The initial theme is set based on the value stored in local storage. If no theme is stored, the default is set to light.
• Load Utterances Function: This function determines the theme for Utterances based on the value stored in local storage. It creates a new script element for Utterances, sets the appropriate attributes, and appends it to the discussion-container element. Any previous Utterances script is cleared before appending the new script.
• DOM Content Loaded Event: The loadUtterances function is called when the DOM content is fully loaded to ensure that the Utterances script is loaded with the correct theme.
• Local Storage Change Event: An event listener is added to listen for changes in local storage. If the selected-theme key changes, the loadUtterances function is called to reload the Utterances script with the new theme. By following these steps, you can ensure that the Utterances theme updates dynamically based on the selected theme stored in local storage.

5. Deploy Your Blog

• Save the changes and deploy your blog.
• When a visitor opens a blog post, the Utterances widget will automatically create or link to an issue in your GitHub repository.

Testing Your Setup

1. Open a blog post on your website.
2. Scroll down to the comments section.
3. Go to your GitHub repository (blog-comments) and check the Issues tab.
   • You should see a new issue created for the blog post.
   • The comment you added will appear as a comment in that issue.

Managing Comments

All comments are stored as issues in your GitHub repository. You can:

• Reply to Comments: You can respond directly in the GitHub issue.
• Label Discussions: Use GitHub labels to organize comments (e.g., "Feedback," "Question").
• Moderate Content: Since it’s GitHub, you can easily delete or hide inappropriate comments.

Wrapping Up

Using Utterances to add comments to your blog is simple, efficient, and developer-friendly. You get a modern commenting system that’s transparent and secure, and your readers get a smooth commenting experience.

If you have any questions or need help setting it up, feel free to leave a comment below (powered by Utterances, of course 😉).

Happy blogging!