[Feature] Staticman v3 Support

[VincentTam]

Resolves #115. Demo site at https://git.io/bjsm18, source at https://git.io/bjsm0. A port of Minimal Mistake's Staticman support. CSS has been compiled from SCSS with an online compiler, so there may be some unused properties.

Due to Staticman's public API instance bottleneck eduardoboucas/staticman#227, the default API endpoint is set to the one associated with @staticmanlab, my public API instance for GitLab.

I've added a line in the MIT license to give Michale Rose tribute for his code.

[daattali]

Thanks for adding the code and instructions. In the instructions, "send an invitation to the public GitLab instance @staticmanlab" - can you explain what that means, what needs to be done? Does clicking on the URL below it perform that invitation, or is that the next step?

[VincentTam]

Excuse me for the lack of clarity. A picture like

would illustrate the idea of "invitation" much clearer. The next step is to fire an HTTP GET request to the URL.

The above setup are, in fact, parallel with the with setting up the site & repo config YML files. However, to organize them in reading order, I prefer putting the GitHub invitation first because the response from the Staticman API instance gives users a sense that the static comment service is working.

This instructions echoes those on Staticman's official website, except that I've replaced them with my public instance because of the linked Staticman issue. (It's reported that the project owner's public API instance can no longer accept invitation.)

N.B. My current Staticman API instance is hosted on a free Heroku dyno, which should never be used for production. Consequently, the server idles after 30 minutes of inactivity. When a comment is sent while the server is idling, it is, luckily, not lost, but subject to an expected delay of 15-20s for server restart. One always has the possibility to host his/her owner API instance. The original intention to build my own one is to test Staticman's native GitLab support, so that fits role of a free Heroku dyno. It's a coincidence that custom API servers provide two workarounds for the linked Staticman issue (either migrate to GitLab or stay on GitHub, in both cases, an alternate agent is needed).

[daattali]

Thanks for all your work. I've finally given staticman a quick look and it does look very useful, and I see that you built that bot for everybody's help, so thank you from everyone else too :)

I haven't looked into the PR in too much detail yet, I have a few basic questions first:

• Why is it called v3 if staticman is at v2? Do you mean v3 because it's using your API rather than the official one?
• To make sure i understand: first I need to add staticmanlab as a collaborator, and then the next step is to go to the heroku URL?
• In the config.yml file, what is recaptcha for, is it mandatory when using staticman, and how do you fill out its values?
• If the config.yml file stays as is, with the staticman parameters existing but set to empty strings, would all the staticman css and all associated html/JS be included on the rendered pages?

[VincentTam]

Thanks for your thoughtful questions.

The source code (deploy branch) of my API instance is forked from ntsim/staticman dev branch, so my instance includes eduardoboucas/staticman#219 (and 231 as well). The project owner did build a public testing instance https://dev.staticman.net, whose displays "Hello from Staticman version 3.0.0!". However, he didn't (and perhaps won't) disclose its associated GitLab account. As a result, I've responded to his question by building a public GitLab instance.

I'm using v3 because this shows that v3 works for GitHub, and indicates that this also works for GitLab. "v3" is the version number found in Nicolas Tsim's code merged against the dev branch of the official repo.

Yes for the second question, with a remark that the URL is not Heroku specific. Staticman v3 URL scheme is documented in the linked PR.

The role of reCAPTCHA in config.yml is to provide optional support for this great tool. While writing README, I've forgotten to add an important point about reCAPTCHA. The site secret has to be encrypted by

GET v3/encrypt/SITE_SECRET

"No" for the last question. You'll see that I'm finally using the same logic as disqus.html: empty parameters will evaluate to false.

By the way, I'm not expert in CSS, so please feel free to change the display. I've simply copied Minimal Mistakes' one to minimize my mistakes made during deployment 😂.

Credits:

1. Eduardo Bouças for Staticman
2. Nicolas Tsim for PR 219
3. Michael Rose for the Jekyll template code

[daattali]

Thanks for all the details.

Regarding the recaptcha - if it's for use within staticman, do you think it would make sense to add it as a parameter nested inside staticman instead of its own parameter? And in order to not overload the README, maybe add a comment in the config file about howto fill out the recaptcha params?

[daattali]

I've modified the README a bit, can you also make sure what I wrote is correct and makes sense? I haven't tried this feature yet, I wrote it based on my understanding.

[VincentTam]

I'm neutral on your suggestion about refactoring site.recaptcha to site.staticman.recaptcha. Beautiful Hugo, the Hugo port of this theme has actually implemented that, whereas I'm following Minimal Mistakes's config.yml. I speculate that Michael Rose has left recaptcha outside staticman for the possible use of other comments provider(s) in the future.

If you want recaptcha nested inside staticman, replacing all instances of site.recaptcha with site.staticman.recaptcha will do.

I've found your edit on README clearer than mine. I would suggest adding a screenshot like

since README is to get users set up the blog in minutes, and human minds read pictures much quicker than text.

I've missed an important point about encrypting reCAPTCHA site secrets. I'll edit config.yml template this evening. (I'm replying on mobile.)

[VincentTam]

Modified _config.yml and staticman.yml to give clearer instructions about reCAPTCHA site secret encryption via v3/encrypt, and added a screenshot on collaborator invitation.

[daattali]

Since the recaptcha is only used in staticman for now, and the instructions for it also point to a staticman resource for encrypting the secret, I do prefer it to be a nested parameter under staticman in the config file. Why do the recaptcha parameters have to be repeated twice, once in _config.yml and once in staticman.yml?

[VincentTam]

The client-side _config.yml is for Jekyll templates; staticman.yml is for Staticman API server.

In Staticman v2, Staticman API servers only recognise root level staticman.yml in a GitHub repo. That's documented in step 2 of the Git repo setup.

To understand the separate roles of the two config files, you may view Nicolas Tsim's sample repo at https://gitlab.com/ntsim/test-staticman (its read access requires a GitLab account) provided in Staticman PR 219.

[daattali]

Great, thanks for bearing with me through this.

Last few comments:

• Please add this feature and yourself to CHANGELOG.md
• Can I add in config.yml in the comment for the recaptcha param something along the lines of "If you use recaptcha, you must also set these parameters in staticman.yml"?
• The CSS file has a lot of rules with very generic selectors. This will override many css rules on the entire page. Please prepend all css selectors with .staticman-comments

[VincentTam]

Questions are more than welcome. I'm indebted to Nicolas Tsim's detailed guidance while setting up my public Staticman API instance for GitLab.com.

Some little technical remarks:

1. I apologize for having inadvertently introduced a BOM at the beginning of the CSS file. This has been removed at f4fbd03 on the gh-pages branch for my demo site. To get a cleaner commit history, I squashed it with 3dcbab3 to obtain dcaeaf3. This is invisible on GitHub, but this can be viewed with Git CLI.
2. The commit aab7d05 has introduced a leading whitespace in the change log. While this makes no difference on GitHub, this may break the syntax highlighting in text editors. Therefore, I've removed it.

[daattali]

Thanks for taking such good care, and removing a whitespace from weeks ago. And I didn't notice the BOM - thanks for taking care of that as well.

[daattali]

I merged and tested this out myself on https://daattalitest.github.io/2015-02-28-test-markdown/. Worked really well, thank you!

Two follow up questions:

• Why is email a required field, it doesn't seem to be saved anywhere that's useful even for the repository owner. Is there any way to retrieve the email of a user? If not, I think it should be removed?
• After submitting a comment, I get redirected to a result page that just shows me the result JSON {"success":true,"fields":{"message":"another try","name":"kkk","email":"ed8b33f09416dd8c64479d3f3aa04465","url":"","hidden":"","date":"2018-12-25T23:10:34.191Z"}} - this is not useful for users, they would think an error happened. Can we change it so that an alert box says the comment was submitted, or even just refresh the page, or anything else. The way it currently works is not ideal

[VincentTam]

Thanks for adopting my PR!

I've left 💬 on your test site, and I also observed the raw JSON response coming up instead of the UI text "Thanks for your comment! It will show on the site once it has been approved.". That's a bug in my template. that I've never observed from my experience of building Hugo & Jekyll sites on GitLab. Gimme 5 min to fix that. I've carelessly left beautiful-jekyll in staticman-scripts.html. I've submitted #444 to fix this. Sorry for that 🙉.

• The email field 📧 will be used for gravatar.
• This display of raw JSON reponse is due to the omission of the options[redirect] field in the HTML form a wrong link for loading jQuery in staticman-scripts.html.