From 4867726924deae91fc6548e1086a640def517de8 Mon Sep 17 00:00:00 2001 From: Michael Rose Date: Wed, 21 Nov 2018 14:59:14 -0500 Subject: [PATCH] Add support for utterances (#1966) * Add support for utterances * Add utterances config documentation * Update CHANGELOG and history Close #1909 --- CHANGELOG.md | 1 + _config.yml | 4 +- _includes/comments-providers/scripts.html | 2 + _includes/comments-providers/utterances.html | 20 +++++++++ _includes/comments.html | 3 ++ docs/_config.yml | 4 +- docs/_docs/02-structure.md | 2 +- docs/_docs/05-configuration.md | 43 +++++++++++++++----- docs/_docs/18-history.md | 3 +- docs/_pages/about.md | 4 +- test/_config.yml | 4 +- 11 files changed, 72 insertions(+), 18 deletions(-) create mode 100644 _includes/comments-providers/utterances.html diff --git a/CHANGELOG.md b/CHANGELOG.md index 2536fc328f0f..be0d69df6258 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,7 @@ ### Enhancements +- Add support for [utterances](https://utteranc.es/) comments. [#1909](https://github.com/mmistakes/minimal-mistakes/issues/1909) - Use privacy aware embed options for YouTube and Vimeo in [responsive video helper](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#responsive-video-embed). [#1964](https://github.com/mmistakes/minimal-mistakes/pull/1964) - Add `rel="nofollow noopener noreferrer"` to author profile links. [#1924](https://github.com/mmistakes/minimal-mistakes/pull/1924) - Improve color contrast of primary buttons and links. diff --git a/_config.yml b/_config.yml index 08264e5e90c0..ffba6269f0e2 100644 --- a/_config.yml +++ b/_config.yml @@ -27,7 +27,7 @@ teaser : # path of fallback teaser image, e.g. "/assets/images # breadcrumbs : false # true, false (default) words_per_minute : 200 comments: - provider : # false (default), "disqus", "discourse", "facebook", "google-plus", "staticman", "staticman_v2" "custom" + provider : # false (default), "disqus", "discourse", "facebook", "google-plus", "staticman", "staticman_v2", "utterances", "custom" disqus: shortname : # https://help.disqus.com/customer/portal/articles/466208-what-s-a-shortname- discourse: @@ -37,6 +37,8 @@ comments: appid : num_posts : # 5 (default) colorscheme : # "light" (default), "dark" + utterances: + theme : # "github-light" (default), "github-dark" staticman: allowedFields : # ['name', 'email', 'url', 'message'] branch : # "master" diff --git a/_includes/comments-providers/scripts.html b/_includes/comments-providers/scripts.html index fb3fb79f0f9e..ff9e31c22c9f 100644 --- a/_includes/comments-providers/scripts.html +++ b/_includes/comments-providers/scripts.html @@ -12,6 +12,8 @@ {% include /comments-providers/staticman.html %} {% when "staticman_v2" %} {% include /comments-providers/staticman_v2.html %} + {% when "utterances" %} + {% include /comments-providers/utterances.html %} {% when "custom" %} {% include /comments-providers/custom.html %} {% endcase %} diff --git a/_includes/comments-providers/utterances.html b/_includes/comments-providers/utterances.html new file mode 100644 index 000000000000..b1c08f3cd8eb --- /dev/null +++ b/_includes/comments-providers/utterances.html @@ -0,0 +1,20 @@ + \ No newline at end of file diff --git a/_includes/comments.html b/_includes/comments.html index 2f5f88b312dc..488e31f7ecb2 100644 --- a/_includes/comments.html +++ b/_includes/comments.html @@ -165,6 +165,9 @@

{{ site.data.ui-text[site.locale].comments_labe {% endif %} + {% when "utterances" %} +

{{ comments_label }}

+
{% when "custom" %}
{% endcase %} diff --git a/docs/_config.yml b/docs/_config.yml index 4f087b6dc996..cbe7238411b3 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -22,7 +22,7 @@ teaser : # path of fallback teaser image, e.g. "/assets/images # breadcrumbs : false # true, false (default) words_per_minute : 200 comments: - provider : "staticman_v2" # false (default), "disqus", "discourse", "facebook", "google-plus", "staticman_v2", "staticman" "custom" + provider : "staticman_v2" # false (default), "disqus", "discourse", "facebook", "google-plus", "staticman_v2", "staticman", "utterances", "custom" disqus: shortname : discourse: @@ -32,6 +32,8 @@ comments: appid : num_posts : # 5 (default) colorscheme : # "light" (default), "dark" + utterances: + theme : # "github-light" (default), "github-dark" staticman: allowedFields : # ['name', 'email', 'url', 'message'] branch : "master" diff --git a/docs/_docs/02-structure.md b/docs/_docs/02-structure.md index a177c5728c67..5c7016364d8d 100644 --- a/docs/_docs/02-structure.md +++ b/docs/_docs/02-structure.md @@ -17,7 +17,7 @@ minimal-mistakes | └── ui-text.yml # text used throughout the theme's UI ├── _includes | ├── analytics-providers # snippets for analytics (Google and custom) -| ├── comments-providers # snippets for comments (Disqus, Facebook, Google+, and custom) +| ├── comments-providers # snippets for comments | ├── footer # custom snippets to add to site footer | ├── head # custom snippets to add to site head | ├── feature_row # feature row helper diff --git a/docs/_docs/05-configuration.md b/docs/_docs/05-configuration.md index a2413971f7c0..03fba71552aa 100644 --- a/docs/_docs/05-configuration.md +++ b/docs/_docs/05-configuration.md @@ -2,7 +2,7 @@ title: "Configuration" permalink: /docs/configuration/ excerpt: "Settings for configuring and customizing the theme." -last_modified_at: 2018-11-19T15:35:29-05:00 +last_modified_at: 2018-11-21T14:46:33-05:00 toc: true --- @@ -274,7 +274,7 @@ To disable reading time for a post, add `read_time: false` its YAML Front Matter ### Comments -[**Disqus**](https://disqus.com/), [**Discourse**](https://www.discourse.org/), [**Facebook**](https://developers.facebook.com/docs/plugins/comments), **Google+**, and static-based commenting via [**Staticman**](https://staticman.net/) are built into the theme. First set the comment provider you'd like to use: +[**Disqus**](https://disqus.com/), [**Discourse**](https://www.discourse.org/), [**Facebook**](https://developers.facebook.com/docs/plugins/comments), **Google+**, [**utterances**](https://utteranc.es/), and static-based commenting via [**Staticman**](https://staticman.net/) are built into the theme. First set the comment provider you'd like to use: | Name | Comment Provider | | ---------------- | ------------------------- | @@ -284,6 +284,7 @@ To disable reading time for a post, add `read_time: false` its YAML Front Matter | **google-plus** | Google+ Comments | | **staticman_v2** | Staticman v2 | | **staticman** | Staticman v1 (deprecated) | +| **utterances** | utterances | | **custom** | Other | Then add `comments: true` to each document you want comments visible on. @@ -323,9 +324,9 @@ For guidance on how to set up Discourse for embedding comments from a topic on a ```yaml comments: - provider : "discourse" + provider: "discourse" discourse: - server : # meta.discourse.org + server: # meta.discourse.org ``` **Note:** Do not include `http://` or `https://` when setting your Discourse `server`. The theme automatically prepends the URL `//`, following a scheme-less pattern. @@ -337,11 +338,31 @@ To enable Facebook Comments choose how many comments you'd like visible per post ```yaml comments: - provider : "facebook" + provider: "facebook" facebook: - appid : # optional - num_posts : # 5 (default) - colorscheme : # "light" (default), "dark" + appid: # optional + num_posts: # 5 (default) + colorscheme: # "light" (default), "dark" +``` + +#### utterances Comments + +To use utterances you will need to [install the app](https://github.com/apps/utterances) to your GitHub repository by adding the following to `_config.yml`: + +```yaml +repository: # GitHub username/repo-name e.g. "mmistakes/minimal-mistakes" +``` + +**Note:** Make sure the repo is public, otherwise your readers will not be able to view the issues/comments. The [issues feature](https://guides.github.com/features/issues/) also needs to be active on your repo. +{: .notice--warning} + +To enable utterances on the front end set `comments.provider` and the color theme of the widget. + +```yaml +comments: + provider: "utterances" + utterances: + theme: "github-light" # "github-dark" ``` #### Static-Based Comments via Staticman @@ -361,11 +382,11 @@ Transform user comments into `_data` files that live inside of your GitHub repos ##### Configure Staticman -**Staticman v3** +###### Staticman v3 Due to the support for GitLab, the URL scheme has been changed. Bewteen `v3` and `/entry`, one needs to input a Git service provider (either `github` or `gitlab`). Apart from that, the setup for GitHub remains the same. -**Staticman v2** +###### Staticman v2 Default settings have been provided in [`staticman.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/staticman.yml) and are commented to guide you through setup. View the [full list of configurations](https://staticman.net/docs/configuration). @@ -406,7 +427,7 @@ comments: **Note:** Staticman is currently compatible with GitHub and GitLab based repositories. [Support for GitLab Pages](https://github.com/eduardoboucas/staticman/issues/22) is already available at [Staticman v3](https://github.com/eduardoboucas/staticman/pull/219). {: .notice--warning} -**Staticman v1 (deprecated)** +###### Staticman v1 (deprecated) Default settings have been provided in `_config.yml`. The important ones to set are `provider: "staticman"`, `branch`, and `path`. View the [full list of configurations](https://staticman.net/docs/configuration). diff --git a/docs/_docs/18-history.md b/docs/_docs/18-history.md index fa2f2983f00e..2156a816b3c2 100644 --- a/docs/_docs/18-history.md +++ b/docs/_docs/18-history.md @@ -4,7 +4,7 @@ permalink: /docs/history/ excerpt: "Change log of enhancements and bug fixes made to the theme." sidebar: nav: docs -last_modified_at: 2018-11-21T14:16:10-05:00 +last_modified_at: 2018-11-21T14:55:38-05:00 toc: true --- @@ -12,6 +12,7 @@ toc: true ### Enhancements +- Add support for [utterances](https://utteranc.es/) comments. [#1909](https://github.com/mmistakes/minimal-mistakes/issues/1909) - Use privacy aware embed options for YouTube and Vimeo in [responsive video helper](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#responsive-video-embed). [#1964](https://github.com/mmistakes/minimal-mistakes/pull/1964) - Add `rel="nofollow noopener noreferrer"` to author profile links. [#1924](https://github.com/mmistakes/minimal-mistakes/pull/1924) - Improve color contrast of primary buttons and links. diff --git a/docs/_pages/about.md b/docs/_pages/about.md index 7a669687a03b..10cb1fb47f36 100644 --- a/docs/_pages/about.md +++ b/docs/_pages/about.md @@ -12,7 +12,7 @@ layouts_gallery: - url: /assets/images/mm-layout-archive.png image_path: /assets/images/mm-layout-archive.png alt: "archive layout example" -last_modified_at: 2018-06-04T12:04:24-04:00 +last_modified_at: 2018-11-21T14:49:33-05:00 toc: true --- @@ -31,7 +31,7 @@ Minimal Mistakes is a flexible two-column Jekyll theme. Perfect for hosting your - Several responsive layout options (single, archive index, search, splash, and paginated home page). - Optimized for search engines with support for [Twitter Cards](https://dev.twitter.com/cards/overview) and [Open Graph](http://ogp.me/) data - Optional [header images](https://mmistakes.github.io/minimal-mistakes/docs/layouts/#headers), [custom sidebars](https://mmistakes.github.io/minimal-mistakes/docs/layouts/#sidebars), [table of contents](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#table-of-contents), [galleries](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#gallery), related posts, [breadcrumb links](https://mmistakes.github.io/minimal-mistakes/docs/configuration/#breadcrumb-navigation-beta), [navigation lists](https://mmistakes.github.io/minimal-mistakes/docs/helpers/#navigation-list), and more. -- Commenting support (powered by [Disqus](https://disqus.com/), [Facebook](https://developers.facebook.com/docs/plugins/comments), Google+, [Discourse](https://www.discourse.org/), static-based via [Staticman v1 and v2](https://staticman.net/), and custom). +- Commenting support (powered by [Disqus](https://disqus.com/), [Facebook](https://developers.facebook.com/docs/plugins/comments), Google+, [Discourse](https://www.discourse.org/), [utterances](https://utteranc.es/), static-based via [Staticman v1 and v2](https://staticman.net/), and custom). - [Google Analytics](https://www.google.com/analytics/) support. - UI localized text in English (default), Brazilian Portuguese (Português brasileiro), Chinese, Danish, Dutch, French (Français), German (Deutsch), Greek, Hungarian, Indonesian, Italian (Italiano), Japanese, Korean, Nepali (Nepalese), Polish, Punjabi (ਪੰਜਾਬੀ) Romanian, Russian, Slovak, Spanish (Español), Swedish, Turkish (Türkçe), and Vietnamese. diff --git a/test/_config.yml b/test/_config.yml index 331a33d38cc8..412c01819bc2 100644 --- a/test/_config.yml +++ b/test/_config.yml @@ -21,7 +21,7 @@ teaser : # path of fallback teaser image, e.g. "/assets/images # breadcrumbs : false # true, false (default) words_per_minute : 200 comments: - provider : # false (default), "disqus", "discourse", "facebook", "google-plus", "staticman", "custom" + provider : # false (default), "disqus", "discourse", "facebook", "google-plus", "staticman", "utterances", "custom" disqus: shortname : # https://help.disqus.com/customer/portal/articles/466208-what-s-a-shortname- discourse: @@ -31,6 +31,8 @@ comments: appid : num_posts : # 5 (default) colorscheme : # "light" (default), "dark" + utterances: + theme : # "github-light" (default), "github-dark" staticman: allowedFields : ['name', 'email', 'url', 'message'] branch : # "master", "gh-pages"