Jekyll include for utterances

README.md

Jekyll include for utterances

This is an include to use utterances comments on any Jekyll static site. It is fully compatible with GitHub Pages.

Basic usage

Add utterances.html to your /_includes folder. Put the following include statement in the part of your layout/page/post/include that you want the comments to be in:

{% include utterances.html %}

For most people, eg GitHub Pages users who want the default white theme, this is all you need to do.

Configuration

You can customize utterances both globally (defaults for all comments) or locally (customization for comments on a particular page). Local settings override global settings.

Global settings are set in _config.yml like so:

utterances:
  repo: "mwt/mattwthomas.com"
  issue-term: "pathname"
  label: "utteranc.es"
  theme: "github-light"

You can set local settings by using include parameters like so:

{% include utterances.html repo="mwt/mattwthomas.com" issue-term="pathname" label="utteranc.es" theme="github-light" %}

Common recipies

Name the issues "Comments: Page Title"

{%- assign issue-term = page.title | prepend: 'Comments: ' -%}
{% include utterances.html issue-term=issue-term %}

Use github-dark theme only on pages with dark: true in frontmatter

{%- capture theme -%}
{%- if page.dark -%}
github-dark
{%- else -%}
github-light 
{%- endif -%}
{%- endcapture -%}
{% include utterances.html theme=theme %}

Sidenote

In many themes that come with disqus support you can complete a basic configuration by replacing

{% if site.disqus %}
    {% include disqus.html %}
{% endif %}

with

{% include utterances.html %}

utterances.html

<script src="https://utteranc.es/client.js"
        repo="{{ include.repo | default: site.utterances.repo | default: site.github.repository_nwo }}"
        issue-term="{{ include.issue-term | default: site.utterances.issue-term | default: 'pathname' }}"
        {%- if include.label or site.utterances.label -%}
        label="{{ include.label | default: site.utterances.label }}"
        {%- endif -%}
        theme="{{ include.theme | default: site.utterances.theme | default: 'github-light' }}"
        crossorigin="anonymous"
        async>
</script>

Thanks @mwt!