utterance / utterances

:crystal_ball: A lightweight comments widget built on GitHub issues

utterances 🔮

A lightweight comments widget built on GitHub issues. Use GitHub issues for blog comments, wiki pages and more!

• Open source. 🙌
• No tracking, no ads, always free. 📡🚫
• No lock-in. All data stored in GitHub issues. 🔓
• Styled with Primer, the css toolkit that powers GitHub. 💅
• Dark theme. 🌘
• Lightweight. Vanilla TypeScript. No font downloads, JavaScript frameworks or polyfills for evergreen browsers. 🐦🌲

how it works

When Utterances loads, the GitHub issue search API is used to find the issue associated with the page based on url, pathname or title. If we cannot find an issue that matches the page, no problem, utterances-bot will automatically create an issue the first time someone comments.

To comment, users must authorize the utterances app to post on their behalf using the GitHub OAuth flow. Alternatively, users can comment on the GitHub issue directly.

configuration

sites using utterances

• Haxe documentation and cookbook
• sadsloth.net
• danyow.net
• and many more...

Are you using utterances? Add the utterances topic on your repo!

try it out 👇👇👇

utterances's Issues

Ignore anchors when using "Issue title contains page URL" mode5

I use autogenerated anchors for every heading on my site for a table of contents. When clicking such an anchor link the URL changes to example.com#anchor-title. When I now refresh the page (i.e hit F5), the comment section stays empty because utterances looks for an issue title with the correct #anchor-title. If I now post a comment a new issue is created for the same page.

To fix this, I would propose to just ignore any anchors when doing URL matching, or at least providing an option to do so. What do you think?

Auth Error when signing in to comment

I am encountering this error when I tried to sign in my blog. I also checked other sites using utterance and it is showing the same error.

Migrate comments from disqus

Fixed maximum width of timeline

First of all: Thanks for Utterances. Its exactly what I need for my blog. 👍

There is just one single line of code that's bugging me a little bit:

utterances/src/_timeline.scss

Line 2 in 7c518a0

max-width: 760px;

It would be great if the width css rule of the timeline class could be unset with an additional script tag parameter (or be set to 100% by default).

With kind regards,
Philip Trauner

utterances doesn't connect to GitHub account - Chrome on Android

Even though utterances successfully authorized as GitHub App, it doesn't work on mobile Chrome (Android).

On the regular desktop browser, everything works as expected, the mobile version still shows "Sign in to comment".

When clicking the sign-in button, following screen is shown:

Environment:

• Chrome 71.0.3578.99
• Android 8.1.0

What do you mean by this ?

<script src="https://utteranc.es/client.js" repo="ergo9ine/sfdb_tracker" issue-term="index" theme="github-dark" crossorigin="anonymous" async></script>

SyntaxError: An invalid or illegal string was specified utterances.10cca43d.js:1

utterances requires too many permissions

Hello I wanted to use this but when I went to send a comment it says it needs full access to edit my repos?

---

utterances by utterance wants to access your rain-1 account

Repositories: Public only
This application will be able to read and write all public repository data. This includes the following:

• Code
• Issues
• Pull requests
• Wikis
• Settings
• Webhooks and services
• Deploy keys

SecurityError: The operation is insecure

Firefox is complaining about an operation being insecure, but I'm not sure what. Haven't had time to debug yet, but I'm using FF 55.0.2 (64-bit). I've attached a screenshot of the error output as well.

Happy to share the blog URL if that's helpful at all - it's entirely possible (read: likely) that I'm being a doofus. Really nice idea though, and nice execution - love the idea of GH issues as comments.

load more than 100 comments

virtualize?

fix <select> appearance in safari

appearance:none

move oauth and bot to azure

Self hosting instructions

Hello, I have a question to ask. Your server is blocked in my area, how can I copy your program to my own server?

Unable to comment on mobile browsers

First, Thank you for this amazing work.

Environment

• Device: Galaxy Note 8
• Browser: Google Chrome & Samsung Internet

I just added utterances into my blog and it works very well,
except on mobile browsers.

When I click on "Sign in to comment", a webview opened up and it seems not does redirect me to callback url properly.

Comments counts

First i want to thank you, this is awesome and easy to implement.

I want to know if there is a way to reference the number of comments in a post to use it in another section of the page (say, in the list of posts titles).

Thank you

Why the outer div doesn't get height style automatically?

I recently add this on my site, and discovered that outer div's height style is not set automatically. So it remains 0px height, and I cannot see anything. If I manually change height to some value like 500px, then the content is showed.. Can't know why 😢

apps/utterances landing page needs more guidance

Please provide more info at https://github.com/apps/utterances, since this page is linked to as "Learn more about utterances" in the permissions flow. Users not familiar with utterances or the concept of blog comments hosted by github will need a better orientation to decide whether they want to grant permissions.

Thank you for considering

GDPR

I'm using utterances on a couple of sites, but is it GDPR compliant? I wasn't able to find any signs.. and isn't it necessary to offer anonymous comments?

Support Subresource Integrity

You're able to ensure the integrity of any scripts you load by making use of SRI:

<script src="https://utteranc.es/client.js"
         repo="cryptolosophy/cryptolosophy.org"
         issue-term="pathname"
         integrity="sha384-DPph3TeQWMfa+DwFjWGnI1hGXuOXw4Kpg3Uk/m+qAlgnQJ0njBscbs8AT11PFwZB" crossorigin="anonymous"
         async>
</script>

But if the script you're loading changes, then SRI breaks and browsers will refuse to load it completely. I could just host the script locally to ensure that it doesn't change but then I'd lose the benefits of CDN caching and also I don't really understand the intricacies of utterances to be sure that it'd work perfectly that way.

So what do you recommend?

Support for email replies

Email replies to issues currently show the comments to which the emailer replied without any styling. I would like to ask if it is possible to hide the comment history behind an expand link (...) like on Github and to render it like quoted text similar to Github, or to just completely hide the comment history in the Utterances comment.

Example reply:
https://github.com/PhilipVis/philipvis.github.io/issues/3#issuecomment-430946403

To see how this is currently rendered by Utterances, look at the comments section on page https://verummeum.com/blog/2018/10/14/portable-package-formats/.

Image upload

Enable pasting images via CTRL+V.

jquery html() insert script, issue-term error...?

function utteranc(index){
	$(".blockquote-footer>cite:nth-child(1)").html(index); //dummy
	$("#dolldiscussion")
		.html(`<script src='https://utteranc.es/client.js' repo='ergo9ine/sfdb_tracker' issue-term='${index}' theme='github-dark' crossorigin='anonymous' async><\/script>`);
};

Error: "issue-term" or "issue-number" must be specified.

${index} is number. but, This is not the threads number.
Number unique to the document.

CORS and Cloudeflare problems

Hi @jdanyow

I just changed may blog comments from Disqus to Utterances and got several problems:

1. CORS: as a logged-on user while trying to post a comment:
   

2. Cloudeflare while trying to logon:
   
   https://twitter.com/davepermen/status/1064450165057167360

Is this a new problem? Didn't get this errors last week while trying it out.
Did I forget something?

Here is my blog with the new Utterances comments:
https://asp.net-hacker.rocks/

EDIT:
The CORS error happens on this site as well:
https://www.swifttalking.com/writing-mocks-manually-in-swift/

Thanks,
Juergen

Create issue with just the post title

Specifying issue-term="title" gives both the title of the post and the whole blog, which for me is something like You're up and running! – Isaac Woods – 17 year-old student, building low-level stuff in Rust, which is really long as an issue name. Could we maybe have a issue-term="posttitle" or something to just use the title of the post?

Self-hosting instructions page

Add page with self-hosting instructions.

Current instructions:
#42 (comment)

markdown preview tab

Add the ability to preview the markdown entered into the comment box.

Remove support for Internet Explorer 11 as of July 2018?

GitHub is removing support for Internet Explorer 11 soon:

Should utterances remove it's support for IE 11 at the same time?

There's a few IE polyfills/hacks in the codebase:

1. polyfills:
   

   utterances/src/index.html

   Lines 19 to 28 in e82d1df

   	<script>
   	if (!window.Promise || !window.fetch) {
   	document.write(
   	'<script src="https://cdnjs.cloudflare.com/ajax/libs/bluebird/3.5.0/bluebird.min.js" integrity="sha256-/l7dZnd9iW5Iw9P2Qn/0ghByeFDKnIcPd4DTptDaK20=" crossorigin="anonymous"><\/script>',
   	'<script src="https://cdnjs.cloudflare.com/ajax/libs/fetch/2.0.3/fetch.min.js" integrity="sha256-aB35laj7IZhLTx58xw/Gm1EKOoJJKZt6RY+bH1ReHxs=" crossorigin="anonymous"><\/script>',
   	'<script src="https://cdnjs.cloudflare.com/ajax/libs/classlist/1.1.20170427/classList.min.js"><\/script>',
   	'<script src="https://cdn.jsdelivr.net/npm/[email protected]/custom-event-polyfill.min.js"><\/script>'
   	);
   	}
   	</script>

2. document.currentScript not supported.
   

   utterances/src/client.ts

   Lines 4 to 9 in e82d1df

   	let script = document.currentScript as HTMLScriptElement;
   	if (script === undefined) {
   	// Internet Explorer :(
   	// tslint:disable-next-line:max-line-length
   	script = document.querySelector('script[src^="https://utteranc.es/client.js"],script[src^="http://localhost:4000/client.js"]') as HTMLScriptElement;
   	}

Make ctrl+enter submit comment

Make ⌘ + ENTER submit comment

dark theme?

My site uses a dark theme, how can I style utterances to be dark?

Internet Explorer 11 support

Need to polyfill promise and fetch

Bug Report - wrong links base url generation (markdown)

If you paste this markdown code into comment textarea:

[google](google.com)

You will see next html-code:

<a href="google.com" target="_blank" rel="noopener">google</a>

And it looks ok, but.. no:

"Base url" is https://utteranc.es/, "iframe" context, relative link

Maybe this need to be fixed?

can i change language for comments

can i change default english language of github to my Mother tongue ?

Request - Anonymous comments

I wonder if there could be a way to allow anonymous comments. This could allow someone to comment who doesn't have a GitHub account. Maybe it would trigger a GitHub bot to post the comment on their behalf.

Support for Gitlab

Hi!

I would like to own the data (comments) posted on my website by using the self-hosted Gitlab instance. So is it possible to use Gitlab issues instead of Github issues?

Thanks!

Build Error

I got an error if I build the project. It happens in optimize step:

yarn run optimize

[...]
$ inliner --skip-absolute-urls debug/utterances.html > dist/utterances.html 
fs.js:584
  return binding.open(pathModule._makeLong(path), stringToFlags(flags), mode);
                 ^

Error: ENOENT: no such file or directory, open '/tmp/utterances/node_modules/svgo/lib/svgo/../../.svgo.yml'
    at Error (native)
    at Object.fs.openSync (fs.js:584:18)
    at Object.fs.readFileSync (fs.js:431:33)
    at module.exports (/tmp/utterances/node_modules/svgo/lib/svgo/config.js:31:48)
    at new module.exports (/tmp/utterances/node_modules/svgo/lib/svgo.js:21:19)

Please check svg/svgo#622 , maybe it's the solution.

PS: THANK you for opening the source code - you did a great job!

How can I use utterances on a page with a non-white background?

Utterances currently forces the iframe that is being injected to have a white background color, which makes it possibly not-so-pretty on pages that do not share the plain white background:

It would be relatively trivial to make body have background-color: transparent and .comment have background-color: white (as seen here), but I would assume this is an unwanted breaking change for others.

Are there established ways of doing this yet? In case not, would you be open to adding some customization options to the script? Maybe something like adding data-background-color to the script tag itself?

dark theme support for <kbd> elements

Feature request - jsdelivr.com for client.js

For better versioning and code delivering maybe you will use service https://www.jsdelivr.com/ for client.js?

Service is ree for all ;)

Possibility to add custom message to initial post

Would it be possible to provide a custom/additional message to the initial post created by the bot?

<script src="https://utteranc.es/client.js"
        repo="[ENTER REPO HERE]"
        issue-term="[ENTER TERM HERE]"
        issue-body="[CUSTOM MESSAGE HERE]"
        async>
</script>

Utterances appears on site.com/stg but not on site.com

Hi,
I'm using Utterances on my personal blog on it's all good. I decided to use on a second website (static).

I'm confused about this behavior. Both have the exact same code.

• Works here — https://play-with-ghost.com/stg
• Does not work here — https://play-with-ghost.com/

Do you see why something would prevent the loading on the root of my site?

Thanks!

Integrations page

Add page with links to integrations like react-utterances.

How to delete/hide unwanted comments?

Though I hid comments on the corresponding GitHub Issue page (because they are abusive), utterances still continues to show those comments on my blog post.

Since the comments are posted with utterances, I (owner) cannot just delete them (the ... button does not appear in the comments posted with third-party apps).

How can I remove them from the blog post? Thanks in advance!

Update: I contacted to GitHub and thankfully they deleted the comments that were a problem. Though I think it is better to hide comments on blog posts that are hidden in the corresponding issue pages (is it possible?).

homepage

utterances

A lightweight commenting system using GitHub issues.

http://utteranc.es/index.html

2 different pages have the same comments

2 different pages have the same comments

• https://if2012.github.io/post/my-first-post/

• https://if2012.github.io/post/travis-basis/

there is only 1 issue starifly/blog-comments#1 and both pages display it.

tests

Some possible modifications?

I've been testing this tool for a while. It looks great and it's incredible simple, but I have some ideas that could be interesting to have as a blogger.

First, would it be possible to hide the 'new comment' section using, for example, a parameter? I would like to show only the current comments, but I you want to write a new comment, you have to go to the GitHub issue page.

In this case, it would be great if using another parameter you could show a button to open the Github issue page. I mean, a meaningful button that links to the same page that opens the current number of comments link. It could be valid too if it were somethig like [1] at the begining and/or the end of the comments section.

Lastly, I would like to modify slightly the style of the iframe content. Maybe an optional paramater (yes, one more) to send the changes in the style of the generated page, like font size, background color, maximum width, etc.

These are only some ideas that I have been thinking about while using this tool. For me is fully functional right now - Nice work! -, but I would love to have some of these features at some point.

Thanks.

[1]

Feature Request: Tagged Releases

what

• Tag releases

why

• To enable version pinning (without gitrefs)

reactions

Implement reactions

Multiple issues for same page (threads)

I really love the GitHub-powered feedback integration on docs.microsoft.com which allows multiple issues (each with their own comments) to be attached to a single content page, rather than just individual comments on a single issue.

This sort of organization works particularly well for documentation sites since issues can be addressed and then removed from the default view and allowing those responsible for the documentation to ensure they've responded to each request! It's even more valuable when the content itself lives on GitHub since issues that resolve the problems can be linked directly to the commits which resolve them!

It seems that Utterances is the open-source version of the Microsoft docs commenting implementation, but currently lacks the additional dimension (unless I'm missing something).

I'm curious if this is on the roadmap for utterances!

2 different pages have the same comments

2 different pages have the same comments

• https://rain-1.github.io/shell
• https://rain-1.github.io/shell-2

there is only 1 issue rain-1/rain-1.github.io#3 and both pages display it. I guess it's because of the "-2" bit?

Comments showing on home page

As an example, on this page there are comments:
https://dennisdel.com/blog/

However, when we look at the comment, it should be associated with a different page:
https://dennisdel.com/blog/building-docs-for-nuget-packages-with-vsts-and-github-pages/