Migracja systemu komentarzy z Utterances do Giscus

19.09.2022, 15:50 BST

5 min.

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

Migracja systemu komentarzy z Utterances do Giscus

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.

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ć”.

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.

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.

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.

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).

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ł.

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.

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.

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.

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.

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.

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.