diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 103 |
1 files changed, 98 insertions, 5 deletions
@@ -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 }} </div> ``` + +## 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. + +  + + Then help **[@staticmanlab](https://github.com/staticmanlab)** + accept the invitation by going to + + https://staticman3.herokuapp.com/v3/connect/github/<username>/<repo-name> + +  + + Now, **[@staticmanlab](https://github.com/staticmanlab)** has been + invited to your repository. + +  + + - 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. |