Ten wpis opisuje jak zainstalować generator statycznych stron Hugo na Windowsie. Jak go skonfigurować i stworzyć w nim bloga. Pokażę jak skonfigurować odpowiednio gita (bo to też ważne) i w końcu jak ją opublikować na GitHub Pages.

Wstęp

TL;DR
Opis jak doszło do powstania tego bloga. Jak chcesz techniczne mięsko to przeskocz do następnego rozdziału.

Jak w 2018 roku zaczynałem blogować, to mój blog miał być miejscem na różne rzeczy, których nauczyłem się w czasie pracy. Rozwiązania jakichś problemów, instrukcja jak coś skonfigurować itp.

W tym czasie, w pracy również zaczęliśmy korzystać z systemu kontroli wersji GIT, wcześniej używaliśmy TFS (Team Foundation Server). Zacząłem poznawać gita coraz bardziej i odkrywałem w nim coraz więcej ficzerów, różnych możliwości rozwiązań. Wtedy bardzo polubiłem gita.

Właśnie o gicie napisałem pierwsze 2 posty. Git jest tak elastyczny w działaniu, że jedną rzecz można zrobić na kilka sposobów. W każdym kolejnym tygodniu poznawałem nowe rzeczy, który opisywałem na blogu.

Zamiast bloga o programowaniu, powstał mi blog w całości poświęcony systemowi kontroli wersji Git. Bloga przemianowałem na poznajgita.pl i pisałem tylko o gicie - od lipca 2018 do kwietnia 2020 - czyli prawie 2 lata.

Potem zapał na pisanie o gicie minął. Bardzo dużo nauczyłem się o gicie, a na blogu jakoś nie chciało mi się pisać totalnych podstaw. Większość wpisów dotyczyło jakichś ciekawych ukrytych możliwości gita lub były to instrukcje jak zrobić konkretnę rzecz.

Wróciłem do pierwotnych założeń i na blogu o gicie pojawiło się kilka postów w ogóle nie związanych z tym tematem. Na początku nie chciało mi się do tego stawiać nowego bloga, do wpisów innych niż git, więc zostały one opublikowane na blogu poznajgita.pl.

Jednak wreszcie nadszedł ten czas i postanowiłem postawić nowego bloga na wpisy nie związane z gitem, właśnie teraz go czytasz 😃

Hugo: Instalacja i konfiguracja

Pracuję na Windowsie i do instalacji Hugo skorzystałem z tego poradnika:

Gdy Hugo mam już zainstalowanego tworzymy nową stronę poleceniem:

hugo new site quickstart

Powstał katalog o nazwie quickstart zawierający dane naszej strony.

Musimy dodać jeszcze skórkę do naszej strony. Wykonujemy:

cd quickstart
git init
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke

Wybór skórek jest bardzo dużo. Można je przejrzeć tutaj: https://themes.gohugo.io/. Skórkę dodajemy jako submoduł, aby nie trzeba było trzymać tych plików w naszym repozytorium.

W pliku konfiguracyjnym config.toml musimy jeszcze dodać wpis, że używany tej skórki, dodajemy na końcu linijkę:

theme = "ananke"

Możemy dodać jakiś testowy wpis:

hugo new posts/my-first-post.md

Wpis stworzył w się w katalogu content\posts.

Uruchamiamy serwer poleceniem:

hugo server -D

Pod adresem localhost:1313 możemy zobaczyć naszą stronę.

Opcja -D oznacza, aby pokazywał wpisy, które są jeszcze szkicami (ang. draft). Jak otworzysz plik content\posts\my-first-post.md to zobaczysz, że ma on ustawienie draft = true. Publikacja postu polega po prostu na zmianie tego ustawienia na false (no i oczywiście wrzuceniu strony na serwer 😃 )

Nie będę w tym wpisie opisywał jak działa Hugo, jak pisać posty itd. Wszystyko jest opisane w dokumentacji Hugo: https://gohugo.io/documentation/. Chcę tutaj tylko opisać jak zainstalować, skonfigurować i wrzucić naszą stronę na GitHub Pages.

Google Analytics

Zakładam, że posiadasz konto Google oraz założysz sobie konto w Google Analytics dla właśnie tworzonej strony.

Google Analytics coś ostatnio się zmieniło i nie udostępnia już kodu śledzenia, który możemy wkleić w konfiguracji naszej strony, tak jak jest napisane w dokumentacji: https://gohugo.io/templates/internal#configure-google-analytics

Dla naszej strony trzeba stworzyć nową usługę i dodać strumień danych (Administracja -> 2 kolumna -> Strumienie danych). Po stworzeniu strumienia w sekcji Instrukcje tagowania ma Globalny tag witryny (gtag.js)

Kod ten trzeba umieścić w sekcji <head> na każdej stronie, którą chcesz monitorować. Żeby to zrobić w Hugo wystarczy ten kod umieścić w jednym miejscu. U mnie to będzie ten plik:

\layouts\_default\baseof.html

Wklejamy kod do sekcji <head>

<!DOCTYPE html>
<html lang="{{ .Site.Language }}">
    <head>
        {{ partial "head.html" . }}

        <!-- Global site tag (gtag.js) - Google Analytics -->
		<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXX"></script>
		<script>
		  window.dataLayer = window.dataLayer || [];
		  function gtag(){dataLayer.push(arguments);}
		  gtag('js', new Date());

		  gtag('config', 'G-XXXXXXXX');
		</script>
    </head>

Tworzenie strony w Hugo opiera się na szablonach, czyli każda strona jest stworzona z wielu elementów, które są wykorzystywane na różnych stronach. Jak kod zostanie tam wklejony to będzie widoczny na każdej stronie.

Po wrzuceniu kodu na serwer zbieranie statystyk zacznie działać.

Komentarze

Tworząc bloga na Wordpressie system komentarzy jest od razu tam wbudowany. W przypadku statycznych stron trzeba ogarnąć jakiś zewnętrzny system. Hugo wspiera Disqus, można jednak użyć również innego systemu komentarzy. Obsługiwane systemy można znaleźć tutaj: https://gohugo.io/content-management/comments/.

Ja zdecydowałem się na utterances, ponieważ:

Wszystkie komentarze są zapisywane jako GitHub Issues w moim repozytorium. Czyli pozostają moje 😃 Nie chciałem innych systemów właśnie z tego powodu, aby komentarze nie były gdzieś na jakimś serwerze, tylko u mnie.
Prosta konfiguracja. Nie trzeba mieć dodatkowego serwera czy usługi. Dodaję do stronki skrypt i wszystko działa.

Minusem tego rozwiązania jest to, że nie da się przenieść komentarzy - jeśli już jakieś mamy pod wpisami - z innego systemu. Każdy komentarz to przecież musi być GitHub Issue.

Konfiguracja Gita

W następnym rozdziale będziemy wrzucać naszą stronkę na serwer, więc to się przyda.

Jeśli masz ustawione w konfiguracji gita core.autocrlf true to jest wszystko OK. Druga opcja to linią .gitattributes z linią na początku * text=auto - jeśli to masz to też jest OK 👍

Chodzi mi o zakończenie linii (line endings). Jeśli pracujesz na Linuxie lub macOS, to tego problemu nie doświadczysz. Ja jednak korzystam z Windowsa.

Możesz o tym problemie więcej przeczytać tutaj: https://www.edwardthomson.com/blog/git_for_windows_line_endings.html

Ja akurat robiłem tego bloga na kompie po formacie. Musiałem przed startem zainstalować git i inne potrzebne narzędzia. Całkowicie o tym zapomniałem, nie zwróciłem uwagi na komunikaty w konsoli podczas commitowania kodu i przez to straciłem trochę czasu.

Po wrzuceniu już wygenerowanego kodu, strona nie do końca działała. Wyglądało na to jakby CSS się nie załadowały.

Uruchomiłem w Google Chrome narzędzia dewelopera (F12) i w konsoli był błąd: Failed to find a valid digest in the 'integrity' attribute for resource

Trochę googlowania i znalazłem chodzi właśnie o znaki końca linii: https://github.com/xianmin/hugo-theme-jane/issues/269

GitHub Pages

Zostało nam tylko opublikowanie naszej strony. Wcześniej uruchamialiśmy serwer poleceniem hugo server -D. Jednak jak skończyliśmy pracę na blogiem lub nowym postem trzeba wygenerować pliki naszej strony. Odpalamy Hugo po prostu poleceniem

hugo

Pojawił się nowy katalog public i tam właśnie znajdują się pliki naszej strony. Pliki z tego katalogu trzeba wrzucić na serwer.

Cały proces deploymentu jest dobrze opisany w dokumentacji, o tutaj -> https://gohugo.io/hosting-and-deployment/hosting-on-github/. Nie będę tego przepisywał. Nawet jest tam przygotowany skrypt, pomagający w deployu naszej stronki. Fajnie 👍

Do powstania naszego blog ostatecznie są potrzebne 3 repozytoria:

Dane bloga w formie zrozumiałej dla narzędzia Hugo. Pliki konfiguracyjne + pliki Markdown.
Gotowa do opublikowania strona.
Repozytorium z wybraną przez Nas skórką.

Repozytorium z pkt. 1 jest główne, pozostałe są do niego dołączone jako submoduły.

Pamiętaj o odpowiedniej konfiguracji Gita. Patrz poprzedni rozdział.

Podsumowanie

W tym momencie mamy już postaniowego bloga przy użyciu narzędzia Hugo. Jest już widoczny w intenecie. Można dodawać komentarze do wpisów, a statystyki odwiedzin zbierają się w Google Analytics.

Pozostaje tylko wypełnić go treścią.

Statyczna strona zrobiona w Hugo na Windowsie, opublikowana na GitHub Pages