Migracja systemu komentarzy z Utterances do Giscus

Migracja systemu komentarzy z GitHub Issues (opartego na Utterances) do GitHub Discussions (przy pomocy Giscus) na stronie opartej o Hugo.
Zawartość

Odkąd przeniosłem moją stronę na statyczny generator treści oparty na Hugo pozbyłem się szeregu usług, od których byłem zależny, a tak naprawdę nie były one potrzebne.

Na mojej stronie, za czasów WordPress korzystałem z Disqus jako systemu komentarzy. Ten też system przeniosłem do Hugo, ale po tym, jak powodował on więcej problemów, a niżeli to było warte (związanych z prędkością strony), postanowiłem to zmienić.

W moich przygodach z przenoszeniem komentarzy skończyłem na Utterances.

Utterances pozwala zbudować system komentarzy, który obsługiwany jest po stronie GitHub w postaci Issues.

Wszystko działa bardzo dobrze i tak naprawdę nie miałem potrzeby na zmianę. Jedynie co mnie poniekąd irytowało, to fakt, że komentarze to tak naprawdę nie są problemy (Issues), które wymagają rozwiązania, a które są bardzo przydatne na GitHub do innych celów.

Z GitHub Issues zawsze mi to nie grało. Według mnie używałem tego w zły sposób i poniekąd miałem rację.

W ramach konwersacji o systemie komentarzy Isso na forum Hugo jeden użytkownik wspomniał o giscus.

Get started with GitHub Discussions

Nie wiem dokładnie kiedy, ale GitHub wprowadził coś takiego jak GitHub Discussions, który bardziej pasuje do tego, do czego obecnie używam utterances.

Giscus jest bardzo podobny do Utterances i to nie bez powodu, gdyż w dużej mierze inspirowany jest tym oto rozwiązaniem, przez co nie ma się co dziwić, że cel i rezultat jest podobny.

Po obejrzeniu filmiku promocyjnego na stronie GitHub Discussions stwierdziłem, że spróbuje.

Co ciekawe, dla osób, które już używały Utterances na swojej stronie, istnieje oficjalny sposób na ich migrację z Issues do Discussions. Zachęciło mnie to jeszcze bardziej do poszybowania w tym kierunku.

Włączenie GitHub Discussions #

Co ciekawe, GitHub Discussions nie jest dostępny domyślnie tak jak GitHub Issues i należy go w prosty sposób “włączyć”.

GitHub Settings General Features Discussions

W tym celu przechodzimy do ustawień naszego repozytorium (Settings) i w sekcji ogólne (General) przesuwamy do dołu do sekcji Features gdzie zaznaczamy Discussions.

Po zaznaczeniu klikamy w zielony przycisk Set up discussions.

GitHum Discussions Start a new discussion

W tym kroku możemy utworzyć tak zwany wpis powitalny, który będzie swojego rodzaju wprowadzeniem, dla osób, które odwiedzą twoje GitHub Discussions bezpośrednio, a nie ze strony.

GitHub Discussions idarek/dariusz.wieckiewicz.org

I tak mamy ustawione dyskusje. Pora na implementację na naszej stronie oraz przeniesienie obecnych dyskusji z Issues do Discussions.

Ustawienie Giscus #

W pierwszej kolejności przechodzimy na stronę Giscus.app i sekcji konfiguracja (Configuration).

W pierwszej kolejności wybieramy język, w którym nasza strona będzie obsługiwać komentarze.

Giscus Configuration Language

W pierwszej kolejności ustawiłem Polski jako język, mimo że posiadam również część strony w języku angielskim. W przypadkuj języka angielskiego, zobaczę jak to wprowadzić w dalszej części.

W sekcji repozytorium (Repository) mamy trzy punkty, które musimy spełnić, nim będziemy mogli połączyć nasze repozytorium.

Po pierwsze, nasze repozytorium musi być publiczne, w przeciwnym wypadku odwiedzający nie będą go widzieć i nie będą mogli dodać komentarza.

Instalacja aplikacji Giscus #

Następnie musimy zainstalować aplikację Giscus na naszym koncie GitHub. W tym celu przechodzimy na odpowiednią stronę, na której przyciskamy przycisk instaluj (Install).

Install Giscus app on GitHub

Podczas instalacji możemy wybrać, aby ta aplikacja miała dostęp do wszystkich naszych repozytoriów lub tylko wybranego. W moim przypadku wybrałem tylko jedno, na który będę go używał.

Install Giscus app on GitHub on selected repository

Ostatnim, trzecim krokiem jest włączenie GitHum Discussions, które zrobiliśmy na samym początku.

Pora na wprowadzenie naszego repozytorium, które w moim przypadku jest idarek/dariusz.wieckiewicz.org.

Giscus Configuration Repositoru Success

Powiązanie Giscus z naszą stroną #

W części Page ↔️ Discussions Mapping musimy ustawić, w jaki sposób komentarze dodane na naszej stronie będą powiązane z dyskusjami po stronie GitHub.

Jeżeli czytałeś mój poprzedni wpis “Migracja systemu komentarzy — utterances”, to wiesz, że w moim przypadku wybrałem powiązanie za pomocą linku do wpisu (pathname), dokładnie tak jak w Utterances.

Giscus Configuration Page Discussions Mapping

Domyślne kategoria dla dyskusji #

W przypadku Utterances każdy nasz komentarz oznaczany był odpowiednią etykietą (label). W przypadku Giscus możemy określić domyślną kategorię.

W moim przypadku wybrałem kategorię General.

Giscus Configuration Disscussion Category

Opcje dodatkowe #

W sekcji Features mamy jeszcze do wybrania kilka opcji.

Oprócz samych dyskusji (komentarzy) możemy dodać możliwość dodania reakcji do naszego wpisu. Dzięki temu nasi czytelnicy mogą nam dodać kciuk w górę 👍, nawet gdy niekoniecznie mają coś do dodania w postaci komentarza.

Opcja Emit discussion metadata mnie za bardzo nie interesuje, więc pozostawiam niezaznaczoną.

W Utterances domyślnie dodanie nowego komentarza odbywało się poprzez rozpoczęcie dyskusji pod ostatnim komentarzem. Tutaj możemy zaznaczyć Place the comment box above the comments jeżeli chcemy, aby można było dodać komentarz zaraz po przeczytaniu wpisu. Osobiście wolę, aby osoby, które zdecydują się dodać komentarz, najpierw przeczytały, co inni mieli do powiedzenia, gdyż czasami znajduje się tam odpowiedź na ich pytanie. W związku z tym ponownie pozostawiam tę opcję niezaznaczoną.

Ostatnia opcja (Wczytaj komentarze leniwie) powinna być zaznaczona, ze względu na wpływ komentarzy na wydajność strony. Nie ma potrzeby wczytywania skryptu komentarzy, nim użytkownik przejdzie do końca wpisu.

Giscus Configuration Features

Motyw (wygląd) #

W pozycji motyw (Theme) możemy określić, jak będzie wyświetlać się system komentarzy na naszej stronie.

Jako że na mojej stronie mam ustawiony motyw jasny i ciemny, który się zmienia wraz z ustawieniami użytkownika, pozostałem przy domyślnym wyborze Preferred color scheme.

Giscus Configuration Theme

Kod na stronę #

Na ostatnim etapie, w części Enable giscus otrzymamy nasz kod do wklejenia na naszej stronie.

<script src="https://giscus.app/client.js"
        data-repo="idarek/dariusz.wieckiewicz.org"
        data-repo-id="{repo_ID}"
        data-category="General"
        data-category-id="{category_ID}"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="bottom"
        data-theme="preferred_color_scheme"
        data-lang="pl"
        data-loading="lazy"
        crossorigin="anonymous"
        async>
</script>

Tutaj jak zauważysz mamy opcję data-lang="pl" która odpowiada językowi, który wybraliśmy na początku.

W przypadku mojej angielskojęzycznej części strony zmienię to na data-lang="en".

Dodanie Giscus do naszej strony #

W moim przypadku otworzyłem plik giscus.html w layouts\partials do którego wkleiłem powyższy kod.

Od siebie dodałem jeszcze słowo defer na początku, aby dodatkowo opóźnić ładowanie skryptu podczas ładowania strony, szczególnie gdy nie jest on jeszcze potrzebny.

<script defer src="https://giscus.app/client.js"

W pliku single.html odpowiedzialnym za wyświetlanie mojego wpisu na stronie dodałem odwołanie do mojego pliku w miejscu, gdzie zdecydowałem się wyświetlić komentarze.

Aktualizując z Utterances do Giscus zmieniłem {{ partial "utterances.html" }} na {{ partial "giscus.html" }}

Dodanie obsługi dodatkowego języka #

Mój powyższy kod domyślnie wczytuje się w języku polskim, nawet na stronie w języku angielskim. Aby to zmienić powyższe odwołanie do partial zmieniamy na następujące:

  {{ if eq .Lang "en"}}
    {{ partial "giscus.en.html" . }}
  {{ else }}
    {{ partial "giscus.html" . }}
  {{ end }}

W tym przypadku skopiowałem plik giscus.html do giscus.en.html i ustawiłem data-lang="en"

Jeżeli strona wyświetlona jest domyślnie w języku angielskim, wówczas giscus.en.html zostanie załadowany (zawierający data-lang="en"), w każdym innym przypadku załadowany zostanie giscus.html (zawierający data-lang="pl").

Dostosowanie za pomocą CSS #

Reakcje, komentarz oraz formularz dodania komentarza, domyślnie wyświetla się dostosowany do pełnej szerokości okna za pomocą następującego stylu:

  .giscus, .giscus-frame {
    width: 100%;
    min-height: 150px;
  }

  .giscus-frame {
    border: none;
    color-scheme: normal;
  }

Aby dostosować, jak będzie zachowywać się system komentarzy na naszej stronie, możemy dodać do naszego stylu odpowiednią klasę .giscus oraz .giscus-frame.

W moim przypadku do stopki artykułu dodałem .giscus

@media (min-width: 835px) {
  .article-footer,
  .giscus {
    width: 65vw;
    margin: 0 auto;
  }
}

Migracja komentarzy z GitHub Issues do GitHub Discussions (opcjonalne) #

W momencie, gdy wszystko mamy w pełni działające możemy przystąpić do przeniesienia komentarzy, które zostały utworzone za pomocą Utterances (GitHub Issues) do dyskusji obsługiwanej przez Giscus.

GitHub posiada oficjalną metodę na tego typu zabiegu, w sekcji Converting an issue to a discussion.

Przechodząc do sekcji Issues w naszym repozytorium, klikając na poszczególne wpisy (po kolei, niestety — osobiście miałem 44), z menu po prawej stronie wybieramy opcję Convert to discussion.

W momencie rozpoczęcia dyskusji, przy pomocy Utterances, każdy GitHub Issues zawiera pierwszy wpis utworzony przez “utterances-bot”. Ten wpis nie jest wyświetlany, jeżeli używamy Utterances. W momencie przeniesienia obecnego Issue do Discussion, Giscus (który jest inspirowany Utterances) ma to na uwadze i szanuje (pomija) ten wpis, dzięki czemu, po przeniesieniu wpisu z GitHub Issues do GitHub Discussions pojawi się on automatycznie na naszej stronie w odpowiednim miejscu.

Podczas konwersji zapytani zostaniemy, do jakiej kategorii powinniśmy zaklasyfikować nasz wpis. W moim przypadku tak jak wybrałem na początku konfiguracji, wybieram opcję General.

Convert GitHub Issues to GitHub Discussion

Całość potwierdzamy przyciskiem I understand, convert this issue.

Odinstalowanie Utterances #

W momencie, gdy przenieśliśmy nasze komentarze z Utterances do Giscus, możemy usunąć (odinstalować) aplikację Giscus.

Aby tego dokonać przechodzimy do ustawień zainstalowanych aplikacji w GitHub.

Klikając odpowiednio przycisk konfiguracji (Configure), a następnie na dole strony wybieramy opcję odinstalowania (Uninstall “utterances”).

I to by było na tyle.

Takim sposobem mamy w użyciu GitHub Discussions jako system komentarzy na naszej stronie.

Pozdrawiam.

Komentarze