Staticman documentation enhancement

README.md

@@ -118,8 +118,12 @@ To use Facebook comments, create a Facebook app using [Facebook developers](http
 
 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`.
 
+Notes: You may choose other Staticman API instance.  In this case, adjust the collaborator, the above invitation link and `endpoint` in the Staticman section of `_config.yml` accordingly.  In addition, the parameters `<username>` and `<repo-name>` are case-sensitive.
+
 Optional: It is suggested to enable reCAPTCHA to avoid massive spam comments.  You may refer to `_config.yml` for detailed instructions.
 
+Optional: You might want to configure a webhook to prevent inactive branches representing merged comments from stacking up.  You may refer to [Staticman's documenation](https://staticman.net/docs/webhooks) for details.  Please 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
 
 To use JustComments you first need to have an account. After you just need to copy the API key to the `just-comments` property in `_config.yml` file.

_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
+# Staticman support (parameters under this section are CASE-sensitive)
 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`
-  endpoint   : # URL of your own deployment (with trailing slash) (will fallback to a public GitLab instance)
+  endpoint   : # URL of your own deployment (with 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,8 +23,8 @@ comments:
 
   # (*) REQUIRED
   #
-  # Name of the branch being used. Must match the one sent in the URL of the
-  # request.
+  # Name of the branch being used. Must match the `branch` in the theme config
+  # file.
   branch: "master"   #  use "master" for user page
   #branch: "gh-pages" #  use "gh-pages" for project page
 
@@ -98,11 +99,12 @@ comments:
 
   # reCAPTCHA (OPTIONAL)
   # Register your domain at https://www.google.com/recaptcha/ and choose reCAPTCHA V2
-  # Use your OWN siteKey and secret.
+  # To enable reCAPTCHA, set `enabled` to "true", and uncomment `siteKey` and `secret`
+  # below, and use your OWN ones.
   reCaptcha:
     enabled: false
-    siteKey: "6Lcv8G8UAAAAAEqV1Y-XEPum00C_DxhD6O--qkFo"
+    #siteKey: "6Lcv8G8UAAAAAEqV1Y-XEPum00C_DxhD6O--qkFo"
     # (!) 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
-    secret: "p5uHlH9hCqpMJaGKXdt5MEWFo7K6fX8hoYUwR3aIafOI6rtItLauaDCkGOucysJtrVZy+sHffioGzMsOU64JFDSyPQgrXujegcOHFRXHhD4fOUuBXSvV+OZ8JhSPTGWaRcQcoiGX4pT5hlebLddOl59b6sn6kU1ODQcEbhP83xVLZlaTWOrNrF5Wvy3TMXpH5gyl1tZEORxADAShMYyUbNR7XZYLEg1DfgIBHfIg3cKwdFt7KVLejFGKIiBYRAZDE2JuHItNmzJ2x9JgSK3E+XnShV5tuWpncnyFonJVHGEky/zRfUVLHobDMcJ/u9nlZqE8u47W+833F1WaIYuwNw=="
+    #secret: "p5uHlH9hCqpMJaGKXdt5MEWFo7K6fX8hoYUwR3aIafOI6rtItLauaDCkGOucysJtrVZy+sHffioGzMsOU64JFDSyPQgrXujegcOHFRXHhD4fOUuBXSvV+OZ8JhSPTGWaRcQcoiGX4pT5hlebLddOl59b6sn6kU1ODQcEbhP83xVLZlaTWOrNrF5Wvy3TMXpH5gyl1tZEORxADAShMYyUbNR7XZYLEg1DfgIBHfIg3cKwdFt7KVLejFGKIiBYRAZDE2JuHItNmzJ2x9JgSK3E+XnShV5tuWpncnyFonJVHGEky/zRfUVLHobDMcJ/u9nlZqE8u47W+833F1WaIYuwNw=="