Wstęp#

W ramach przeglądu rozwiązań do obsługi komentarzy na blogach statycznych, wziąłem na warsztat Giscus. To narzędzie typu open-source, które wykorzystuje GitHub Discussions jako swój backend.

Zaintrygowała mnie przede wszystkim obietnica wydajności i prywatności.Poniżej przedstawiam analizę tego rozwiązania, instrukcję implementacji w Hugo oraz wnioski z testów wydajnościowych.

Czym właściwie jest Giscus?#

Giscus to widget, który łączy Twoją stronę bezpośrednio z API GitHuba. Kiedy czytelnik zostawia komentarz pod wpisem, system automatycznie tworzy nową dyskusję (lub dopisuje odpowiedź) w powiązanym repozytorium na GitHubie.

Z perspektywy architektury to genialne w swojej prostocie rozwiązanie:

  • Zero bazy danych – wszystkim zarządza GitHub.
  • Brak trackingu – nie ma tu skryptów śledzących użytkownika po całej sieci.
  • Markdown – komentarze obsługują pełny GitHub-flavored markdown (kod, tabele, linki).

Wymagania wstępne#

Zanim przejdziemy do konfiguracji, musisz wiedzieć o jednym kluczowym ograniczeniu architektonicznym. Giscus wymaga, aby repozytorium przechowywania dyskusji było publiczne. Wynika to z mechaniki działania API GitHuba – skrypt po stronie klienta musi mieć możliwość odczytu dyskusji.

Czego potrzebujemy na start:

  1. Publiczne repozytorium na GitHubie.
  2. Włączoną funkcję “Discussions” w tym repozytorium.
  3. Zainstalowaną aplikację Giscus.

Konfiguracja: Krok po kroku#

Proces integracji jest stosunkowo prosty. Prześlę Cię przez moją ścieżkę konfiguracji dla Hugo.

1. Przygotowanie repozytorium#

Jeśli Twoje repozytorium jest prywatne, musisz zmienić jego widoczność w ustawieniach (Settings -> Danger Zone -> Change repository visibility).

2. Aktywacja Dyskusji i instalacja aplikacji#

W ustawieniach repozytorium (zakładka General -> sekcja Features) zaznaczamy opcję Discussions. Dobrą praktyką jest utworzenie osobnej kategorii dla komentarzy, np. “Comments” typu Announcement.

Następnie instalujemy bota Giscus z adresu github.com/apps/giscus. Przy instalacji wybrałem opcję dostępu tylko do konkretnego repozytorium bloga, co jest bezpieczniejszym podejściem.

3. Generowanie konfiguracji#

Najwygodniej skorzystać z konfiguratora na giscus.app. Kluczowe ustawienia, na które warto zwrócić uwagę:

  • Mapping: Wybrałem pathname. Gwarantuje to, że każdy post będzie miał unikalny wątek dyskusji bazujący na ścieżce URL.
  • Category: Wskazujemy utworzoną wcześniej kategorię “Comments”.
  • Theme: Polecam preferred_color_scheme. Dzięki temu widget automatycznie dostosuje się do trybu jasnego/ciemnego w systemie użytkownika.

4. Integracja z Hugo#

Po wygenerowaniu skryptu, zamiast wklejać go “na sztywno”, stworzyłem elastyczny partial. Pozwala to na łatwe zarządzanie parametrami z poziomu pliku konfiguracyjnego.

Plik: layouts/partials/comments/giscus.html

{{- if .Site.Params.giscus.repo -}}
<script src="https://giscus.app/client.js"
        data-repo="{{ .Site.Params.giscus.repo }}"
        data-repo-id="{{ .Site.Params.giscus.repoId }}"
        data-category="{{ .Site.Params.giscus.category }}"
        data-category-id="{{ .Site.Params.giscus.categoryId }}"
        data-mapping="pathname"
        data-strict="0"
        data-reactions-enabled="1"
        data-emit-metadata="0"
        data-input-position="top"
        data-theme="preferred_color_scheme"
        data-lang="{{ .Language.Lang }}"
        crossorigin="anonymous"
        async>
</script>
{{- end -}}

Zwróć uwagę na linię data-lang="{{ .Language.Lang }}". To prosty trick, który automatycznie przełącza język interfejsu Giscus w zależności od wersji językowej Twojego bloga.

Następnie uzupełniamy plik hugo.toml:

[params]
  commentSystem = "giscus"

# Konfiguracja Giscus (na końcu pliku)
[params.giscus]
  repo = "twoj-username/twoje-repo"
  repoId = "R_kgDO..."  # ID wygenerowane przez giscus.app
  category = "Comments"
  categoryId = "DIC_kwDO..."

5. Dispatcher komentarzy#

Aby zachować porządek w kodzie i łatwość przełączania systemów w przyszłości (np. do kolejnych testów), stosuję prosty “dispatcher”.

Plik: layouts/partials/comments.html

{{- $commentSystem := .Site.Params.commentSystem -}}

{{- if eq $commentSystem "giscus" -}}
  {{ partial "comments/giscus.html" . }}
{{- else if eq $commentSystem "disqus" -}}
  {{ partial "comments/disqus.html" . }}
{{- end -}}

Analiza wydajności i “narzutu”#

Sprawdziłem, jak Giscus wpływa na czas ładowania strony w porównaniu do strony bez komentarzy.

Baseline (brak komentarzy):

  • Transfer: 311 KB
  • Czas ładowania: 1.20s

Z włączonym Giscus:

  • Transfer: 413 KB (+102 KB)
  • Czas ładowania: 4.46s (First Contentful Paint pozostaje bez zmian, skrypt ładuje się asynchronicznie)

Sam Giscus to tak naprawdę jeden plik JS (main.js, ok. 81 KB) i trochę stylów CSS. Całość zamyka się w okolicach 116 KB.

Dla kogo jest to rozwiązanie?#

Po testach mam jasny obraz grupy docelowej.

Giscus to świetny wybór, jeśli:

  1. Twoimi odbiorcami są programiści. Wymóg posiadania konta na GitHubie to naturalny filtr. Dla dev-bloga to zaleta (wyższa jakość dyskusji), dla bloga kulinarnego – dyskwalifikacja.
  2. Zależy Ci na “zielonym” Lighthouse. Niski narzut na wydajność jest kluczowy przy statycznych stronach.
  3. Cenisz Open Source. Kod jest otwarty, darmowy i nie ma reklam.

Warto rozważyć alternatywy, gdy:

  1. Prowadzisz stronę firmową/enterprise i nie możesz upublicznić repozytorium.
  2. Twoi czytelnicy nie są techniczni (konieczność logowania przez GitHub ich odstraszy).

Podsumowanie#

Giscus przeszedł moje testy bardzo pomyślnie. To nowoczesne podejście do komentarzy, które usuwa niepotrzebne dodatki (reklamy, śledzenie, ciężkie skrypty), pozostawiając samą esencję dyskusji.

Integracja z Hugo jest bezproblemowa, a obsługa wielojęzyczności działa “out of the box”. Jeśli Twoja publiczność żyje w ekosystemie GitHuba, jest to obecnie jeden z najciekawszych systemów na rynku.

Zachęcam do samodzielnych testów – konfiguracja zajmuje około 10 minut, a w razie potrzeby powrót do poprzedniego rozwiązania to tylko zmiana jednej linijki w hugo.toml.