From 94161dbef714a6ca0be122b46df3ea2b4e6c4064 Mon Sep 17 00:00:00 2001 From: Vincent Tam Date: Mon, 8 Jul 2019 21:36:17 +0200 Subject: [PATCH] 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 | 4 ++-- _config.yml | 8 ++++---- staticman.yml | 26 ++++++++++++++------------ 3 files changed, 20 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 3281be5..006e497 100644 --- a/README.md +++ b/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//`. 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//`. 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 diff --git a/_config.yml b/_config.yml index a0a09bc..6e765a3 100644 --- a/_config.yml +++ b/_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` - endpoint : # URL of your own deployment (with trailing slash) (will fallback to a public GitLab instance) + 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 a trailing slash (will fallback to a public GitLab instance) eg. https:///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/ diff --git a/staticman.yml b/staticman.yml index 164e97d..d8807ee 100644 --- a/staticman.yml +++ b/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 - # request. - branch: "master" # use "master" for user page - #branch: "gh-pages" # use "gh-pages" for project page + # Name of the branch being used. Must match the `branch` in the theme config + # file. + branch: "master" # use "master" for user page or "gh-pages" for project pages 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 - # Use your OWN siteKey and secret. + # To enable reCAPTCHA: + # 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" - # (!) ENCRYPT reCaptcha secret key using Staticman /encrypt endpoint - # i.e. https://staticman3.herokuapp.com/v3/encrypt/{your-site-secret} - # For more information, https://staticman.net/docs/encryption - secret: "p5uHlH9hCqpMJaGKXdt5MEWFo7K6fX8hoYUwR3aIafOI6rtItLauaDCkGOucysJtrVZy+sHffioGzMsOU64JFDSyPQgrXujegcOHFRXHhD4fOUuBXSvV+OZ8JhSPTGWaRcQcoiGX4pT5hlebLddOl59b6sn6kU1ODQcEbhP83xVLZlaTWOrNrF5Wvy3TMXpH5gyl1tZEORxADAShMYyUbNR7XZYLEg1DfgIBHfIg3cKwdFt7KVLejFGKIiBYRAZDE2JuHItNmzJ2x9JgSK3E+XnShV5tuWpncnyFonJVHGEky/zRfUVLHobDMcJ/u9nlZqE8u47W+833F1WaIYuwNw==" + #siteKey: "" + # ENCRYPT reCaptcha secret key using Staticman /encrypt endpoint + # i.e. https://{STATICMAN API INSTANCE}/v3/encrypt/{your-site-secret} + # For more information, visit https://staticman.net/docs/encryption + #secret: ""