From e4cc16b784298e3b62bad84b5a4210c1f3210d4a Mon Sep 17 00:00:00 2001 From: Vincent Tam Date: Sat, 27 Jul 2019 15:55:26 +0200 Subject: Remove repo specific info --- LICENSE.md | 12 +++++- README.md | 103 +++++++++++++++++++++++++++++++++++++++++++--- exampleSite/config.toml | 29 ++++++++----- exampleSite/staticman.yml | 13 +++++- staticman.yml | 16 ------- 5 files changed, 138 insertions(+), 35 deletions(-) delete mode 100644 staticman.yml diff --git a/LICENSE.md b/LICENSE.md index 290eed8..1102878 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -679,5 +679,13 @@ Staticman integration The MIT License (MIT) -Original work Copyright (c) 2017-2019 Michael Romero -Modified work Copyright (c) 2019 Vincent Tam +Original work Copyright © 2017–2019 Michael Romero +Modified work Copyright © 2019 Vincent Tam + +Staticman locale string +============================================================================== + +The MIT License (MIT) + +Original work Copyright © 2013–2019 Michael Rose +Modified work Copyright © 2019 Vincent Tam diff --git a/README.md b/README.md index 4f5a6a4..1946fac 100644 --- a/README.md +++ b/README.md @@ -17,11 +17,10 @@ As of today **Huginn** supports : - A `gallery` partial to display a nice gallery at the end of your post - Displaying a link and the name of a song you were listening at while writing a post (activated in front-matter with `song: [title](link)`) - Comments powered by [Isso](https://posativ.org/isso/) for -now. A parameter in `config.yaml` is used to specify Isso server -`{{ .Site.Params.isso_server }}` - - Static comments powered by [Staticman](https://staticman.net) v3. -Some parameters in `config.toml` and `staticman.yml` are used to configure -Staticman's API. + now. A parameter in `config.yaml` is used to specify Isso server + `{{ .Site.Params.isso_server }}` + - Static comments powered by [Staticman](https://staticman.net) v3. See the + instructions below to get the service started. ## Lightbox @@ -66,3 +65,97 @@ The `gallery` partial is even more simple. All you have to do is put your images {{ end }} ``` + +## Staticman + +Procedures to start using Staticman: + +1. Add Staticman bot/app, depending on your Git service provider. + - GitHub: choose either one of the following method + + GitHub App: refer to issue + [https://github.com/eduardoboucas/staticman/issues/243](https://github.com/eduardoboucas/staticman/issues/243) + for detailed procedures. + + GitHub bot: invite + **[@staticmanlab](https://github.com/staticmanlab)** as a collaborator + to your repository (by going to your repository's **Settings** page, + navigating to the **Collaborators** tab. + + ![add staticmanlab on GitHub](https://camo.githubusercontent.com/3fe02265b8c1bd484e339c62045fb5a4e701cd71/68747470733a2f2f6769742e696f2f666a5a5078) + + Then help **[@staticmanlab](https://github.com/staticmanlab)** + accept the invitation by going to + + https://staticman3.herokuapp.com/v3/connect/github// + + ![help staticmanlab accept invitation](https://camo.githubusercontent.com/fca08dcc33537c78f0b56e934afde4af0605f706/68747470733a2f2f76696e63656e7474616d2e6769746c61622e696f2f706f73742f323031382d31322d31392d7374617469636d616e2d696e7669746174696f6e2d69732d636173652d73656e7369746976652f696e76697465322e706e67) + + Now, **[@staticmanlab](https://github.com/staticmanlab)** has been + invited to your repository. + + ![staticmanlab invited to GitHub repo](https://camo.githubusercontent.com/eb3d86ecf35497912c485fb2d339d9d3cd962197/68747470733a2f2f76696e63656e7474616d2e6769746c61622e696f2f706f73742f323031382d31322d31392d7374617469636d616e2d696e7669746174696f6e2d69732d636173652d73656e7369746976652f696e76697465332e706e67) + + - GitLab: Add the GitLab user associated with your Staticman API endpoint + (e.g. **[@staticmanlab](https://github.com/staticmanlab)** as a + "**developer**" for your project by going to **Settings → Members → Invite + member**. + + There's *no* invitation acceptance mechanism on GitLab. The invited + member enjoys the privileges once the invitation is sent. Therefore, + there's *no* need to hit `/connect`. + + - Framagit: Since Framagit is a fork of GitLab, the overall setup is similar + to that on GitLab. (Note that the Framagit bot is named as + **[@statimcanlab1](https://framagit.org/staticmanlab1)**.) + +2. Fill in the site config file `config.toml` with reference to the instructions +in the comments. + + Framagit users may choose `gitlab` for `gitProvider` in `config.toml`. + + In case of empty `endpoint`, the public Framagit instance will be used. + + | instance | `endpoint` | + | --- | --- | + | official production | `https://api.staticman.net` | + | GitLab | `https://staticman3.herokuapp.com` | + | Framagit | `https://staticman-frama.herokuapp.com` | + +3. Proceed to the **root-level** repo config file `staticman.yml`. Note that +the name and path of this file *can't* be changed. + + The parameter `moderation` is for comment moderation, and it defaults to + `true`, so each new comment is created as a pull/merge request. If it is + switched to `false`, then Staticman will directly commit against the + configured `branch`. + + If you are working on GitLab/Framagit and you have set `moderation: false`, + depending on your `branch`, you might need the following steps. + + - protected branch (e.g. `master`): Go to **Settings → Repository → + Protected Branches** and permit the GitLab bot to push against that + branch. + - unprotected branch (GitHub's default): *no* measures needed + +4. (Optional, GitHub only) To prevent old inactive branches (representing +approved comments) from piling up, you may set up a webhook according to +[Staticman's documenation](https://staticman.net/docs/webhooks). Make sure to +input the **Payload URL** according to your chosen `endpoint`. For example, the +default `endpoint` is `https://staticman3.herokuapp.com`, so the corresponding +**Payload URL** should be `https://staticman3.herokuapp.com/v1/webhook`. + +5. (Optional, but recommended) To stop spam bots, it's suggested to enable +[reCAPTCHA](https://developers.google.com/recaptcha/docs/display). You may +refer to the site config file for details. + +:information_source: By default, this theme uses the public Framagit instance at +v3 instead of the official instance at v2 due to + +- a requests' quota issue reported in issue + [eduardoboucas/staticman#222](https://github.com/eduardoboucas/staticman/issues/222) + in the official instance at v2; +- abscence of the GitHub bot @staticmanapp associated with the official instance + at v2, reported in issue + [eduardoboucas/staticman#306](https://github.com/eduardoboucas/staticman/issues/306); +- a "too many requests" issue + [eduardoboucas/staticman#279](https://github.com/eduardoboucas/staticman/issues/279) + in the official instance at v3. diff --git a/exampleSite/config.toml b/exampleSite/config.toml index 702c99c..18beb3e 100644 --- a/exampleSite/config.toml +++ b/exampleSite/config.toml @@ -1,15 +1,22 @@ -baseURL = "https://staticman-gitlab-pages.frama.io/huginn/" -languageCode = "fr-fr" -defaultContentLanguage = "fr" -title = "Huginn + Framagit + Staticman" +baseURL = "https://example.com/" +languageCode = "en" +defaultContentLanguage = "en" +title = "Site title" theme = "huginn" -# Huginn parameters [Params] avatar = "img/avatar.png" - sitesubtitle = "Un blog libre avec des commentaires" - footer = "Propulsé par [Hugo](https://gohugo.io) et [Staticman](https://staticman.net), thème [Huginn](https://framagit.org/staticman-gitlab-pages/hugo-theme-huginn), CC-BY-SA 4.0." -[Params.staticman] - gitProvider = "gitlab" - repo = "staticman-gitlab-pages/huginn" - branch = "master" + sitesubtitle = "Blog subtitle" + footer = "Powered by [Hugo](https://gohugo.io), theme [Huginn](https://framagit.org/staticman-gitlab-pages/hugo-theme-huginn)" + + # [Params.staticman] + # endpoint = # URL of your own API deployment (without trailing slash), default: "https://staticman-frama.herokuapp.com" + # gitProvider = "gitlab" # either "github" or "gitlab" + # repo = "user/repo" # your GitHub/GitLab repository + # branch = "master" # branch on which you want to receive comments + + # # # If you use reCAPTCHA v2, you must also set these parameters in staticman.yml + # # [Params.staticman.reCaptcha] + # # siteKey = "" # Use your OWN site key, you need to apply for one on Google + # # secret = "" # ENCRYPT your password by going to https:///v3/encrypt/ + diff --git a/exampleSite/staticman.yml b/exampleSite/staticman.yml index 6cdfc67..dd36aa2 100644 --- a/exampleSite/staticman.yml +++ b/exampleSite/staticman.yml @@ -1,6 +1,6 @@ comments: allowedFields: ["name", "email", "website", "comment", "replyThread", "replyName", "replyID"] - branch : "master" + branch : "master" # should match your config.toml commitMessage : "New comment from {fields.name}" path: "data/comments/{options.slug}" filename : "comment-{@timestamp}" @@ -14,3 +14,14 @@ comments: type : "date" options: format : "iso8601" + + # # reCAPTCHA (OPTIONAL) + # # Register your domain at https://www.google.com/recaptcha/ and choose reCAPTCHA V2 + # # Use your OWN siteKey and secret. + # reCaptcha: + # # siteKey and secret should match your config.toml + # siteKey: "6Lcv8G8UAAAAAEqV1Y-XEPum00C_DxhD6O--qkFo" + # # (!) ENCRYPT reCaptcha secret key using Staticman /encrypt endpoint + # # i.e. https://{staticman-endpoint}/v3/encrypt/{your-site-secret} + # # For more information, https://staticman.net/docs/encryption + # secret: "p5uHlH9hCqpMJaGKXdt5MEWFo7K6fX8hoYUwR3aIafOI6rtItLauaDCkGOucysJtrVZy+sHffioGzMsOU64JFDSyPQgrXujegcOHFRXHhD4fOUuBXSvV+OZ8JhSPTGWaRcQcoiGX4pT5hlebLddOl59b6sn6kU1ODQcEbhP83xVLZlaTWOrNrF5Wvy3TMXpH5gyl1tZEORxADAShMYyUbNR7XZYLEg1DfgIBHfIg3cKwdFt7KVLejFGKIiBYRAZDE2JuHItNmzJ2x9JgSK3E+XnShV5tuWpncnyFonJVHGEky/zRfUVLHobDMcJ/u9nlZqE8u47W+833F1WaIYuwNw==" diff --git a/staticman.yml b/staticman.yml deleted file mode 100644 index 6cdfc67..0000000 --- a/staticman.yml +++ /dev/null @@ -1,16 +0,0 @@ -comments: - allowedFields: ["name", "email", "website", "comment", "replyThread", "replyName", "replyID"] - branch : "master" - commitMessage : "New comment from {fields.name}" - path: "data/comments/{options.slug}" - filename : "comment-{@timestamp}" - format : "yaml" - moderation : true - requiredFields : ["name", "email", "comment"] - transforms: - email : md5 - generatedFields: - date: - type : "date" - options: - format : "iso8601" -- cgit v1.2.3