Staticman documentation enhancement (#514)

* Add a link to Staticman: Webhooks

* Clearer README on Staticman reCAPTCHA and endpoint

* Update README after owner's feedback

* Update staticman.yml after owner's feedback

* Further improve Staticman templates

* Corrected Staticman config instructions

* Update staticman.yml

* Update _config.yml

* Update README.md

README.md

@@ -116,9 +116,9 @@ To use Facebook comments, create a Facebook app using [Facebook developers](http
 
 #### Staticman comments
 
-To use Staticman, you first need to invite `staticmanlab` as a collaborator to your repository (by going to your repository **Settings** page, navigate to the **Collaborators** tab, and add the username `staticmanlab`), and then accept the invitation by going to `https://staticman3.herokuapp.com/v3/connect/github/<username>/<repo-name>`. Lastly, fill in your `repository` and `branch` in the Staticman section of `_config.yml`.
+To use Staticman, you first need to invite `staticmanlab` as a collaborator to your repository (by going to your repository **Settings** page, navigate to the **Collaborators** tab, and add the username `staticmanlab`), and then accept the invitation by going to `https://staticman3.herokuapp.com/v3/connect/github/<username>/<repo-name>`. Lastly, fill in the `staticman` parameters in the Staticman section of `_config.yml`. You may also choose a different Staticman instance other than `staticmanlab`.
 
-Optional: It is suggested to enable reCAPTCHA to avoid massive spam comments.  You may refer to `_config.yml` for detailed instructions.
+Optional: You may want to configure a webhook to prevent old inactive branches (representing approved comments) from stacking up.  You can refer to [Staticman's documenation](https://staticman.net/docs/webhooks) for details.  Make sure to input the **Payload URL** according to your chosen `endpoint`.  For example, the default `endpoint` is `https://staticman3.herokuapp.com/v3/entry/github/`, so the corresponding **Payload URL** should be `https://staticman3.herokuapp.com/v1/webhook`.
 
 #### JustComments
 

_config.yml

@@ -126,13 +126,13 @@ url-pretty: "MyWebsite.com"  # eg. "deanattali.com/beautiful-jekyll"
 # To use Facebook Comments, fill in a Facebook App ID
 # fb_comment_id: ""
 
-# Staticman support
+# To use Staticman comments, fill in repository, branch, and endpoint
 staticman:
   repository : # GitHub username/repository eg. "daattali/beautiful-jekyll"
-  branch     : # eg. "master" If you're not using `master` branch, then you also need to update the `branch` parameter in `staticman.yml`
+  branch     : master # If you're not using `master` branch, then you also need to update the `branch` parameter in `staticman.yml`
-  endpoint   : # URL of your own deployment (with trailing slash) (will fallback to a public GitLab instance)
+  endpoint   : # URL of your own deployment, with a trailing slash (will fallback to a public GitLab instance) eg. https://<your-api>/v3/entry/github/
   reCaptcha:
-    # reCaptcha for Staticman (OPTIONAL)
+    # reCaptcha for Staticman (OPTIONAL, but recommended for spam protection)
     # If you use reCaptcha, you must also set these parameters in staticman.yml
     siteKey  : # Use your own site key, you need to apply for one on Google
     secret   : # ENCRYPT your password by going to https://staticman3.herokuapp.com/v3/encrypt/<your-site-secret>

staticman.yml

@@ -4,7 +4,8 @@
 # another one to handle posts.
 # To encrypt strings use the following endpoint:
 # https://{STATICMAN API INSTANCE}/v3/encrypt/{TEXT TO BE ENCRYPTED}
-# {STATICMAN API INSTANCE} defaults to staticman3.herokuapp.com
+# {STATICMAN API INSTANCE} should match the `endpoint` in the theme config
+# file. It defaults to "staticman3.herokuapp.com".
 
 comments:
   # (*) REQUIRED
@@ -22,10 +23,9 @@ comments:
 
   # (*) REQUIRED
   #
-  # Name of the branch being used. Must match the one sent in the URL of the
+  # Name of the branch being used. Must match the `branch` in the theme config
-  # request.
+  # file.
-  branch: "master"   #  use "master" for user page
+  branch: "master"   #  use "master" for user page or "gh-pages" for project pages
-  #branch: "gh-pages" #  use "gh-pages" for project page
 
   commitMessage: "New comment by {fields.name}"
 
@@ -97,12 +97,14 @@ comments:
     email: md5
 
   # reCAPTCHA (OPTIONAL)
-  # Register your domain at https://www.google.com/recaptcha/ and choose reCAPTCHA V2
+  # To enable reCAPTCHA:
-  # Use your OWN siteKey and secret.
+  # 1. Set `enabled` to `true`
+  # 2. Register your domain at https://www.google.com/recaptcha/ and choose reCAPTCHA V2
+  # 3. Uncomment `siteKey` and `secret` and fill them in with your values
   reCaptcha:
     enabled: false
-    siteKey: "6Lcv8G8UAAAAAEqV1Y-XEPum00C_DxhD6O--qkFo"
+    #siteKey: ""
-    # (!) ENCRYPT reCaptcha secret key using Staticman /encrypt endpoint
+    # ENCRYPT reCaptcha secret key using Staticman /encrypt endpoint
-    # i.e. https://staticman3.herokuapp.com/v3/encrypt/{your-site-secret}
+    # i.e. https://{STATICMAN API INSTANCE}/v3/encrypt/{your-site-secret}
-    # For more information, https://staticman.net/docs/encryption
+    # For more information, visit https://staticman.net/docs/encryption
-    secret: "p5uHlH9hCqpMJaGKXdt5MEWFo7K6fX8hoYUwR3aIafOI6rtItLauaDCkGOucysJtrVZy+sHffioGzMsOU64JFDSyPQgrXujegcOHFRXHhD4fOUuBXSvV+OZ8JhSPTGWaRcQcoiGX4pT5hlebLddOl59b6sn6kU1ODQcEbhP83xVLZlaTWOrNrF5Wvy3TMXpH5gyl1tZEORxADAShMYyUbNR7XZYLEg1DfgIBHfIg3cKwdFt7KVLejFGKIiBYRAZDE2JuHItNmzJ2x9JgSK3E+XnShV5tuWpncnyFonJVHGEky/zRfUVLHobDMcJ/u9nlZqE8u47W+833F1WaIYuwNw=="
+    #secret: ""