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
Kategorie