N-archive/hacks-guide-minimal-mistakes-theme
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Add instructions for configuring Staticman v2 comments

Browse source
This commit is contained in:
Michael Rose 2017-10-04 16:32:11 -04:00
parent ab09e1bb43
commit fce0c55f2b
3 changed files with 71 additions and 18 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/_config.yml
View file

@ -20,7 +20,7 @@ teaser : # path of fallback teaser image, e.g. "/assets/images
# breadcrumbs : false # true, false (default) # breadcrumbs : false # true, false (default)
words_per_minute : 200 words_per_minute : 200
comments: comments:
provider : "staticman_v2" # false (default), "disqus", "discourse", "facebook", "google-plus", "staticman", "staticman_v2" "custom" provider : "staticman_v2" # false (default), "disqus", "discourse", "facebook", "google-plus", "staticman_v2", "staticman" "custom"
disqus: disqus:
shortname : shortname :
discourse: discourse:

85
docs/_docs/05-configuration.md
View file

@ -2,7 +2,7 @@
title: "Configuration" title: "Configuration"
permalink: /docs/configuration/ permalink: /docs/configuration/
excerpt: "Settings for configuring and customizing the theme." excerpt: "Settings for configuring and customizing the theme."
last_modified_at: 2017-10-04T11:30:01-04:00 last_modified_at: 2017-10-04T16:31:28-04:00
--- ---
Settings that affect your entire site can be changed in [Jekyll's configuration file](https://jekyllrb.com/docs/configuration/): `_config.yml`, found in the root of your project. If you don't have this file you'll need to copy or create one using the theme's [default `_config.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/_config.yml) as a base. Settings that affect your entire site can be changed in [Jekyll's configuration file](https://jekyllrb.com/docs/configuration/): `_config.yml`, found in the root of your project. If you don't have this file you'll need to copy or create one using the theme's [default `_config.yml`](https://github.com/mmistakes/minimal-mistakes/blob/master/_config.yml) as a base.
@ -241,14 +241,15 @@ To disable reading time for a post, add `read_time: false` its YAML Front Matter
[**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+**, 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 | | Name | Comment Provider |
| ---- | ---------------- | | ---- | ---------------- |
| **disqus** | Disqus | | **disqus** | Disqus |
| **discourse** | Discourse | | **discourse** | Discourse |
| **facebook** | Facebook Comments | | **facebook** | Facebook Comments |
| **google-plus** | Google+ Comments | | **google-plus** | Google+ Comments |
| **staticman** | Staticman | | **staticman_v2** | Staticman v2 |
| **custom** | Other | | **staticman** | Staticman v1 (deprecated) |
| **custom** | Other |
Then add `comments: true` to each document you want comments visible on. Then add `comments: true` to each document you want comments visible on.
@ -311,24 +312,62 @@ Transform user comments into `_data` files that live inside of your GitHub repos
###### Add Staticman as a Collaborator ###### Add Staticman as a Collaborator
1. Allow Staticman push access to your GitHub repository by clicking on **Settings**, then the **Collaborators** tab and adding `staticmanapp` as a collaborator. 1. Allow Staticman push access to your GitHub repository by clicking on **Settings**, then the **Collaborators** tab and adding `staticmanapp` as a collaborator.
2. To accept the pending invitation visit: `https://api.staticman.net/v1/connect/{your GitHub username}/{your repository name}`. Consult the Staticman "[Get Started](https://staticman.net/get-started)" guide for more info. 2. To accept the pending invitation visit: `https://api.staticman.net/v2/connect/{your GitHub username}/{your repository name}`. Consult the Staticman "[Get Started](https://staticman.net/get-started)" guide for more info.
###### Configure Staticman ###### Configure Staticman
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). **Staticman v2**
**Note:** Staticman is currently only compatible with GitHub based repositories. [Support for GitLab Pages](https://github.com/eduardoboucas/staticman/issues/22) is planned but not available yet. 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).
{: .notice--warning}
```yaml
# staticman.yml (defaults)
comments:
allowedFields : ["name", "email", "url", "message"]
branch : "master"
commitMessage : "New comment"
filename : "comment-{@timestamp}"
format : "yaml"
generatedFields:
date:
type : "date"
options:
format : "iso8601"
moderation : true
path : "/_data/comments/{options.slug}" (default)
requiredFields : ["name", "email", "message"]
transforms:
email : md5
```
These settings need to be added to your `_config.yml` file as well:
```yaml
# _config.yml (defaults)
repository : # GitHub username/repo-name e.g. "mmistakes/minimal-mistakes"
comments:
provider : "staticman_v2"
staticman:
branch : "master"
```
**Branch setting:** This is the branch comment files will be sent to via pull requests. If you host your site on GitHub Pages it will likely be `master` unless your repo is setup as a project --- use `gh-pages` in that case. **Branch setting:** This is the branch comment files will be sent to via pull requests. If you host your site on GitHub Pages it will likely be `master` unless your repo is setup as a project --- use `gh-pages` in that case.
{: .notice--info} {: .notice--info}
**Note:** Staticman is currently only compatible with GitHub based repositories. [Support for GitLab Pages](https://github.com/eduardoboucas/staticman/issues/22) is planned but not available yet.
{: .notice--warning}
**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).
```yaml ```yaml
# _config.yml (defaults)
comments: comments:
provider: "staticman" provider: "staticman"
staticman: staticman:
allowedFields : ['name', 'email', 'url', 'message'] allowedFields : ['name', 'email', 'url', 'message']
branch : # "master", "gh-pages" branch : "master"
commitMessage : "New comment." commitMessage : "New comment."
filename : comment-{@timestamp} filename : comment-{@timestamp}
format : "yml" format : "yml"
@ -346,15 +385,29 @@ staticman:
###### Comment Moderation ###### Comment Moderation
By default comment moderation is enabled in `_config.yml`. As new comments are submitted Staticman will send a pull request. Merging these in will approve the comment, close the issue, and automatically rebuild your site (if hosted on GitHub Pages). By default comment moderation is enabled in `staticman.yml`. As new comments are submitted Staticman will send a pull request. Merging these in will approve the comment, close the issue, and automatically rebuild your site (if hosted on GitHub Pages).
To skip this moderation step simply set `moderation: false`. To skip this moderation step simply set `moderation: false`.
**ProTip:** Create a GitHub webhook that sends a `POST` request to the following payload URL `https://api.staticman.net/v1/webhook` and triggers a "Pull request" event to delete Staticman branches on merge. **ProTip:** Create a GitHub webhook that sends a `POST` request to the following payload URL `https://api.staticman.net/v2/webhook` and triggers a "Pull request" event to delete Staticman branches on merge.
{: .notice--info} {: .notice--info}
![pull-request webhook]({{ "/assets/images/mm-staticman-pr-webhook.jpg" | absolute_url }}) ![pull-request webhook]({{ "/assets/images/mm-staticman-pr-webhook.jpg" | absolute_url }})
###### reCAPTCHA Support (v2 only)
To enable Google's reCAPTCHA to aid in spam detection you'll need to:
1. Apply for [reCAPTCHA API](https://www.google.com/recaptcha) keys and register your site using the reCAPTCHA V2 type.
2. Add your site and secret keys to `staticman.yml` and `_config.yml`. Be sure to properly encrypt your secret key using [Staticman's encrypt endpoint](https://staticman.net/docs/encryption).
```yaml
reCaptcha:
enabled: true
siteKey: # "6LdRBykTAAAAAFB46MnIu6ixuxwu9W1ihFF8G60Q"
secret: # "PznnZGu3P6eTHRPLORniSq+J61YEf+A9zmColXDM5icqF49gbunH51B8+h+i2IvewpuxtA9TFoK68TuhUp/X3YKmmqhXasegHYabY50fqF9nJh9npWNhvITdkQHeaOqnFXUIwxfiEeUt49Yoa2waRR7a5LdRAP3SVM8hz0KIBT4="
```
##### Other Comment Providers ##### Other Comment Providers
To use another provider not included with the theme set `provider: "custom"` then add their embed code to `_includes/comments-providers/custom.html`. To use another provider not included with the theme set `provider: "custom"` then add their embed code to `_includes/comments-providers/custom.html`.

2
staticman.yml
View file

@ -100,5 +100,5 @@ comments:
enabled: true enabled: true
siteKey: "6LdRBykTAAAAAFB46MnIu6ixuxwu9W1ihFF8G60Q" siteKey: "6LdRBykTAAAAAFB46MnIu6ixuxwu9W1ihFF8G60Q"
# Encrypt reCaptcha secret key using Staticman /encrypt endpoint # Encrypt reCaptcha secret key using Staticman /encrypt endpoint
# For more inforrmation, https://staticman.net/docs/encryption # For more information, https://staticman.net/docs/encryption
secret: "PznnZGu3P6eTHRPLORniSq+J61YEf+A9zmColXDM5icqF49gbunH51B8+h+i2IvewpuxtA9TFoK68TuhUp/X3YKmmqhXasegHYabY50fqF9nJh9npWNhvITdkQHeaOqnFXUIwxfiEeUt49Yoa2waRR7a5LdRAP3SVM8hz0KIBT4=" secret: "PznnZGu3P6eTHRPLORniSq+J61YEf+A9zmColXDM5icqF49gbunH51B8+h+i2IvewpuxtA9TFoK68TuhUp/X3YKmmqhXasegHYabY50fqF9nJh9npWNhvITdkQHeaOqnFXUIwxfiEeUt49Yoa2waRR7a5LdRAP3SVM8hz0KIBT4="