[documentation] how to use staticman on gitlab?

[robinmoussu]

Staticman seems usable with gitlab, but I wasn't able to understand how to do it. I think that the main documentation should be updated (or at least points to another page) where it explains how to use gitlab.

@VincentTam Do you think it could be possible that you describe what you did on your test. I'm also using hugo, so it would be highly welcome.

[VincentTam]

@robinmoussu I've already done that in my GitLab + Staticman tutorial in September, and here's a more refined version: https://gitlab.com/VincentTam/bhdemo#beautiful-hugo-with-staticman-comment-reply. Nonetheless, I recommend using Framagit (see last section), another GitLab instance, instead of GitLab.com for performance reasons.

Here's some instructions from others for GitLab + Staticman:

1. Using jekyll
2. New year, new blog (Comment no. 2)

Judging from PR's for documentation changes such as #256, #261, #266, #281, I think writing a separate blog post would be a better choice for the moment. You may consider contributing one if you like.

Remarks: #283 shows the value of creating and using alternate API instances : in case of unnotified updates of the NodeJS app, your personal site's commenting service won't suddenly get broken. You can merge and deploy the updates/PR's on your test GitHub/GitLab pages until you're satisfied. Due to the emergence of alternate API instances implementing this NodeJS app at different versions, it's more difficult to converge to a common unified guide. Nevertheless, I'm always pingable here, and my blog and test sites on GitHub, GitLab & Framagit.

[robinmoussu]

Thanks for the quick answer. I tried again, but without success.

I obviously don't understand something, so I tried to sum-up what I understand, and what I tried.

From what I understand, I should add in each blog post a form to be able to send a comment. I think that it's just a configuration somewhere, and when the gitlab CI build my blog, it will add that form automatically at the end of each blog post.
When a user fill that form and click on the "submit" button, a request to a staticman instance should be send (for example to the framasoft instance). The staticman instance will then create a pull request on the gitlab of my blogpost, that should be accepted automatically (if I comments are not moderated). To do that the gitlab user of the framasoft instance of staticman should be added as a developper. That pull request will add a new file in data/comments, and trigger a rebuild of the site (like any PR). Once rebuilded, the blog post will contains the post + the form + the comment.

1. I don't understand how the form (to be able to send the comments) is generated.
2. I cloned https://gitlab.com/VincentTam/bhdemo#beautiful-hugo-with-staticman-comment-reply then did hugo server to test locally. I only have a blank page on my localhost instance, witch is quite impractical for testing. I force pushed it on my blog, and (after the CI builded it), I got the blog posts with the comments. I tried to add a new comment, without success. For obvious reason I reverted this push to the normal content of my blog.
3. I'm not sure that I gave the correct right to the framasoft bot. What is it's username?

[VincentTam]

I think that it's just a configuration somewhere, and when the gitlab CI build my blog, it will add that form automatically at the end of each blog post.

The Go-HTML template file(s) under layouts/partials do the job.

---

Before I proceed, it's better to give a quick response to clarify the roles of my two public GitLab instances.

"name"	"public GitLab instance"	"public Framagit instance"
GitLab instance served	GitLab.com	Framagit
gitlabBaseUrl	https://gitlab.com	https://framagit.org
GitLab Bot	staticmanlab	staticmanlab1
githubBaseUrl	https://github.com	https://github.com
API URL	https://staticman3.herokuapp.com	https://staticman-frama.herokuapp.com

AFAIK, gitlabBaseUrl can only take one GitLab instance. Both of them are run on a Heroku free dyno, which sleeps after 30 minutes of inactivity and has a 20s wake-up time. Heroku's free dyno isn't for production. I've chosen it since the original purpose is to test the GitLab support as well as the unmerged #231.

Remarks: The user name staticmanlab has been taken up by someone else on Framagit, so I have to append the digit '1'.

[VincentTam]

Re-reading my "refined" guide, I'm shocked that two crucial steps are missing. I'll fix this after answering your questions.

The staticman instance will then create a pull request on the gitlab of my blogpost, that should be accepted automatically (if I comments are not moderated)

moderation	true	false
Staticman API server's action	create Merge request	directly push against branch
authorization needed	developer	developer + right to push against protected branch

That pull request will add a new file in data/comments, and trigger a rebuild of the site (like any PR). Once rebuilded, the blog post will contains the post + the form + the comment.

That's the result of several things done well:

1. Staticman (as a NodeJS app) (relay HTML <form> data to GitHub/GitLab repo according to the path found in root-level staticman.yml)
2. CD/CI (for automatic rebuild)
3. Site theme('s Staticman integration) (for displaying static comments)

Items (1) and (3) require a config file. I call the former "(git) repo config", and the later "site config" for clarity.

Staticman (this Git repo, as a a NodeJS app), is only responsible for (1). As long as the API server can transmit the generated data files into the path specified in root-level staticman.yml, then step (1) is good. In case of problems in (3), it's a problem with the site theme.

---

Let's get back to your questions.

1. To generate an HTML form by hand, you may try the HTML <form> element on W3 School's tutorial.
2. Staticman API servers communicate with remote Git servers, not local Git repos.
3. Please see the table in the above comment.

[VincentTam]

Thanks for the quick answer. I tried again, but without success.

@robinmoussu Please include the link to your site as well as your source code, so that other users, apart from me, may also offer a helping hand. Please consider giving the error message and the error code so that your error can be reproduced by others.

After resting for a night, I've reminded myself that I haven't yet clearly addressed the quoted sentence. The GitLab repo for your blog has no root-level staticman.yml. That's why a Staticman API instance can't interact with your repo.

To understand how Staticman (as a NodeJS app) works, I recommend the original demo repo https://gitlab.com/ntsim/test-staticman (require GitLab login to view) posted in #219 (comment). I recommend reading the comments by Nicolas Tsim, the author of that PR, as a reference, especially the top of the page. However, the setup guide mixes up two things: server-side setup and client-side setup. That's why I've written two separate articles in my blog to make things clear for non-developers like me. In addition, the original comments might contain careless mistakes, since our mind might get tired after hours of coding, thinking and writing.

Apart from the lack of repo config in the GitLab repo for your blog, your site template (customized Beautiful Hugo) lacks Go-HTML partial template(s) for Staticman comments display. Despite the offiical GitLab Pages + Hugo demo embed Hugo themes as a subdirectory, it's better to follow Hugo's official quick start guide and embed a Hugo theme as a Git submodule because it's not supposed to be modified as frequently as the blog's content folder. This allows you to easily merge additional features and/or bug fixes in your Hugo theme's PR, such as, halogenica/beautifulhugo#225 for Archive support. You may consider my Staticman nested comment & instant preview support halogenica/beautifulhugo#222 for the Go-HTML template needed to render Staticman comments.

[VincentTam]

2. I cloned https://gitlab.com/VincentTam/bhdemo#beautiful-hugo-with-staticman-comment-reply then did hugo server to test locally. I only have a blank page on my localhost instance, witch is quite impractical for testing.

@robinmoussu I've overlooked this problem. This is due to the lack of the themesDir theme/beautifulhugo, and that's a usage problem of hugo server, not a Staticman problem. You may include the theme Beautiful Hugo by git submodule update --init --remote --recursive. Due to the file .gitmodules, git submodule will set up the themesDir to track my tweaked Beautiful Hugo, which includes some PR's (optional features and bug fixes) of the original theme, notably halogenica/beautifulhugo#222.

Looking back, I should have included the --recurse-submodules in the git clone command in the README of my demo project.

P.S. The code written for nested Staticman integration for the theme Beautiful Hugo in the above linked PR is, in fact, unnecessarily complicated. (c.f. victoriadrake/hugo-theme-introduction#119 (comment)) This has motivated me to retake a Framagit user's abandonned work, simplify the template code and port it into another theme Huginn. The newly developped site should be a better demo.

Demo site: https://staticman-gitlab-pages.frama.io/huginn

[robinmoussu]

Thanks a lot for the support. I'm currently moving home, and I will test that in probably 2 weeks Envoyé depuis ProtonMail mobile

…

-------- Message d'origine -------- On 24 mai 2019 à 13:15, Vincent Tam a écrit :

> - I cloned https://gitlab.com/VincentTam/bhdemo#beautiful-hugo-with-staticman-comment-reply then did hugo server to test locally. I only have a blank page on my localhost instance, witch is quite impractical for testing. ***@***.***(https://github.com/robinmoussu) I've overlooked this problem. This is due to the lack of the themeDir theme/beautifulhugo, and that's a usage problem of hugo server, not a Staticman problem. You may include the theme Beautiful Hugo by git submodule update --init --remote --recursive. Due to the file .gitmodules, git submodule will set up the themeDir to track [my tweaked Beautiful Hugo](https://gitlab.com/vincenttam/beautifulhugo), which includes some PR's (optional features and bug fixes) of the original theme, notably [halogenica/beautifulhugo#222](halogenica/beautifulhugo#222). Looking back, I should have included the [--recurse-submodules](https://stackoverflow.com/q/3796927/3184351) in the git clone command in the README of my demo project. P.S. The code written for nested Staticman integration for the theme Beautiful Hugo in the above linked PR is, in fact, unnecessarily complicated. (c.f. [victoriadrake/hugo-theme-introduction#119 (comment)](victoriadrake/hugo-theme-introduction#119 (comment))) This has motivated me to retake [a Framagit user's abandonned work](https://framagit.org/Bridouz/bridouz.frama.io/commit/f01aca4e3267d87d15057ca596554b3a190bd45f), simplify the template code and port it into another theme [Huginn](https://framagit.org/staticman-gitlab-pages/hugo-theme-huginn). The newly developped site should be a better demo. Demo site: https://staticman-gitlab-pages.frama.io/huginn — You are receiving this because you were mentioned. Reply to this email directly, [view it on GitHub](#293?email_source=notifications&email_token=ABPJZY5K2BPQKB32HD7TVGDPW7E4TA5CNFSM4HN2SXBKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGODWE7DYI#issuecomment-495579617), or [mute the thread](https://github.com/notifications/unsubscribe-auth/ABPJZY7TTSAQTNCE3B52MUDPW7E4TANCNFSM4HN2SXBA).

[VincentTam]

@robinmoussu Bon déménagement et bonne installation !

[VincentTam]

@robinmoussu Here's a related Hugo Discourse question about the problem of blank page in Hugo. I didn't (and won't) read it in details. Perhaps you might find this informative.

[VincentTam]

Update: For a documentation on how to use Staticman with GitLab, I've written an illustrated guide in the README for a recently published Hugo theme called Huginn at https://themes.gohugo.io/huginn/.

[alexwaibel]

Duplicate of #312

[adamzachyang]

After resting for a night, I've reminded myself that I haven't yet clearly addressed the quoted sentence. The GitLab repo for your blog has no root-level staticman.yml. That's why a Staticman API instance can't interact with your repo.

Just found this after trying to set up Staticman on GitLab and was exactly what I was missing. Thanks @VincentTam!