Blog

Hugo Tutorial PL. Odsłona pierwsza.

Pierwszy wpis zaczynający serię tekstów o tym jako korzystać z dobrodziejstw Hugo przy tworzeniu własnej strony.

Hugo Tutorial PL. Odsłona pierwsza.

Moje ciągotki do prokrastynacji w połączeniu z doskwierającymi upałami czy równie często panującą duchotą, sprawiły, że w ostatnich tygodniach ciężko było mi się zająć czymkolwiek poza narzekaniem na aurę i jakieś dolegliwości fizjologiczne. Oczywiście swoje też zrobiły mistrzostwa Starego Kontynentu w szmaciance, choć zarzekałem się, że za wyłączeniem Włochów nie będę oglądał innych spotkań. Pech chciał, że makaroniarze dojechali aż do szczęśliwego końca turnieju, a mi zabrakło jak zawsze konsekwencji i parę innych spotkań również obejrzałem.

Tym niemniej od pewnego czasu czułem, że chyba zbyt wiele było tej laby, nawet jak na moje - raczej hedonistyczne - standardy i pora jednak coś na bloga wrzucić. Pomny, że kilka tygodni temu odgrażałem się, że na warsztat weźmiemy Hugo, rzuciłem się - bardzo delikatnie - w wir poszukiwania mądrości w tym zakresie. Niestety dość szybko wyszło, że chyba odrobinę naściemniałem w moim poprzednim tekście dotyczącym tego “frameworka”, a dokładniej pomyliłem się w przynajmniej dwóch kwestiach. Po pierwsze, wspominałem iż obcowanie z tym generatorem stron statycznych (dalej SSG) nie wymaga znajomości Golang w najmniejszym nawet stopniu i choć w gruncie rzeczy jest to prawda, ale stwierdzenie to wymaga drobnego doprecyzowania, o czym za chwilę. Po wtóre, coś mi się wówczas napisało o całkiem niezłej dokumentacji na stronie tego projektu, ponieważ taka wydała mi się na pierwszy rzut oka. Tutaj mam niestety większego kaca moralnego i dlatego od razu zacznę, iż z tej ostatniej opinii muszę się wycofać. Natomiast po kolei.

Jeśli chodzi o Golang, to faktycznie posługiwanie się Hugo jest wolne od wymogu jakiejkolwiek biegłości w tym języku programowania. Tym niemniej okazuje się, że system szablonów do osadzanie danych w widokach stron został “pożyczony” z biblioteki standardowej Go (chodzi dokładnie o biblioteki html/template i text/template). Tym niemniej trudno uznać, że w tym wypadku mamy faktycznie do czynienia z kodowaniem w tym języku, bo to trochę tak jakbym powiedział, że znając jako tako Jinja2 mogę się uważać za biegłego w Pythonie. Dodatkowo składnia w przypadku tego języka szablonów jest na tyle prosta, że nie powinien mieć problemów z jego opanowaniem średnio ogarnięty osobnik z jako taką znajomością HTML chociażby (a przynajmniej tak się dzieje w przypadku Hugo).

Zdecydowanie większym problemem była dla mnie dokumentacja. Nie napiszę w tym miejscu, że przerosła ona moje możliwości, bo to raczej oczywiste skoro musiałem ratować się innymi źródłami, by jakoś odnaleźć się w tym chaosie. Przy tym nie nie uważam, że sama w sobie jest ona zła, bo jak się już odrobinę ogarnąłem, to obcowanie z nią wydawało się znacznie prostsze. Tym niemniej za grzech ciężki uważam, że na stronie projektu zabrakło jakiegoś obszerniejszego tekstu, który wyjaśniłby - nawet zgrubnie - architekturę całości rozwiązania. Co prawda niemal na początku jest omówienie struktury projektu (w sensie domyślnie tworzonych katalogów i ich potencjalnej zawartości), ale raczej pobieżna i zawierająca liczne odsyłacze do szczegółowych artykułów, których lektura nie popychała mnie niestety do przodu.

STARTUJEMY

Skoro już wyraziłem skruchę pora przejść do rzeczy. Na początek słów kilka o tym, czym się będę zajmował w kilku następnych wpisach, poza oczywistym stwierdzeniem, że będziemy budować własną witrynę. Dlatego w tym miejscu krótko co i w jaki sposób zostanie przedsięwzięte.

Otóż planuję stworzyć prostego, ale w pełni funkcjonalnego bloga przy wykorzystaniu gotowego darmowego motywu w HTML. Utartym zwyczajem wezmę na tapet temat ze strony startbootstrap.com o wdzięcznej nazwie Clean Blog. Jak sama nazwa wskazuje jest to dość niewyszukany i przez to przejrzysty motyw, więc świetnie nadaje się do celów “edukacyjnych”. Tym niemniej przy jego strukturze zamieszamy trochę więcej niż zazwyczaj, tym samym strona główna (domowa) nie będzie zawierała listy - bodajże 4 - wpisów, a jedynie prosty tekst z jakimś nagłówkiem. Wspomniane zestawienie postów zostanie przeniesione na podstronę o nazwie “Blog”, zaś “About” odtworzymy dokładnie w takim samym kształcie jak w bazowym temacie.

Co  ważniejsze ćwiczenie to wykonanym dwa razy. Przy pierwszym podejściu omówię podstawy podstaw i w oparciu o moją wciąż skromną wiedzę na temat Hugo zrobimy go w możliwie najprostszy sposób, co nie znaczy najlepszy: po prostu skorzystamy z absolutnego minimum elementów czy tam funkcjonalności, które daje nam Hugo. Przy drugim podejściu będę chciał wprowadzić dodatkowe rozwiązania, które koniec końców wygenerują mniej więcej te same pliki HMTL, ale całość projektu Hugo będzie bardziej “zwinna”.

Jeśli chodzi o stronę techniczną, to zakładam, że z samym zainstalowaniem Hugo nie powinno być większych problemów, dlatego tej kwestii omawiać nie będę. W przypadku użytkowników Linuksa zwróciłbym jedynie uwagę na fakt, że korzystanie z oficjalnego repozytorium danej dystrybucji nie zawsze jest wskazane, ponieważ dostępna wersja Hugo może być kilka numerków do tyłu w stosunku do tej najbardziej aktualnej. Dla przykładu: gdy piszę te słowa mamy Hugo w wersji 0.85, tymczasem w repo Ubuntu LTS (20.04) króluje numerek 0.68. Nie potrafię - jako świeży użytkownik Hugo - odpowiedzieć, czy między tymi release’ami doszło do jakiś fundamentalnych zmian, tym niemniej zaznaczam, że sam pracuję na wersji najświeższej i ten cykl wpisów właśnie na niej będzie się opierał. Na szczęście jest przynajmniej kilka innych opcji dostępnych niż oficjalne repozytorium, zaś dla użytkowników rodziny “debianowatych” są nawet dostępne odpowiednie paczki w formacje deb.

Dalsze część dzisiejszego wpisu w całości będzie poświęcona przygotowaniu projektu do pracy bez nawet pobieżnego omówienia poszczególnych zagadnień, gdyż tym zajmiemy się w kolejnych odsłonach tego cyklu. Dlatego zaczynamy od utworzenia naszej witryny na komputerze lokalnym i w tym celu odpalamy konsolę, w której przechodzimy do katalogu, w którym posadowimy naszej projekt, a następnie wpisujemy polecenie:

$ hugo new site moj-blog

Wskazana nazwa nie ma większego znaczenia, ale w wyniku takiego a nie innego wyboru zostanie utworzony folder o nazwie “moj-blog” wraz z odpowiednią konfiguracją plików i katalogów, tak jak to widać niżej.

.

├── archetypes

│   └── default.md

├── config.toml

├── content

├── data

├── layouts

├── static

└── themes

Od razu otwórzmy przy pomocy naszego ulubionego edytora default.md w katalogu archetypes, by dokonać zmiany wartości “true” na “false” przy pozycji draft. Cel tego zabiegu wyjaśnię w kolejnych wpisach omawiając między innymi rolę tego pliku w naszym projekcie.

Następnie wracamy do konsoli i przechodzimy do katalogu głównego naszej witryny poleceniem cd /ścieżka_dostępu/moj-blog. Oczywiście ścieżka dostępu powinna odpowiadać strukturze katalogów, w którym utworzyliśmy nasz projekt, czyli w moim przypadku byłoby to:

$ cd Projekty/hugo/moj-blog/

W tym momencie wydajemy polecenie $hugo new theme cb-one, które spowoduje utworzenie w folderze themes szkieletu nowego motywu, z którego zamierzamy skorzystać przy kreowaniu naszej witryny. W efekcie struktura naszego projektu mocno się rozbuduje, co też zostanie później omówione.

Ostatnia czynność do wykonania dzisiaj, to poinformowanie Hugo, że zamierzamy skorzystać z motywu umieszczonego w katalogu /themes/cb-one. Wymaga to otwarcia pliku config.toml i dorzucenia wiersza theme = “cb-one”.

Na ten moment to wszystko. W kolejnym wpisie omówię krótko strukturę projektu i główne zasady jakie nimi rządzą oraz powoli będziemy się zabierać do tworzenie pierwszych treści czy właściwie stron.