Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[documentation] how to use staticman on gitlab? #293

Closed
robinmoussu opened this issue May 18, 2019 · 11 comments
Closed

[documentation] how to use staticman on gitlab? #293

robinmoussu opened this issue May 18, 2019 · 11 comments
Labels
needs docs Signifies that the issue requests a documentation update.

Comments

@robinmoussu
Copy link

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
Copy link
Contributor

VincentTam commented May 18, 2019

@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
Copy link
Author

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
Copy link
Contributor

VincentTam commented May 18, 2019

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
Copy link
Contributor

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
Copy link
Contributor

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
Copy link
Contributor

VincentTam commented May 24, 2019

  1. 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
Copy link
Author

robinmoussu commented May 24, 2019 via email

@VincentTam
Copy link
Contributor

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

@VincentTam
Copy link
Contributor

@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
Copy link
Contributor

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 alexwaibel added the needs docs Signifies that the issue requests a documentation update. label Nov 8, 2019
@alexwaibel
Copy link
Collaborator

Duplicate of #312

@alexwaibel alexwaibel marked this as a duplicate of #312 Nov 8, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
needs docs Signifies that the issue requests a documentation update.
Projects
None yet
Development

No branches or pull requests

3 participants