Hugo dla początkujących

Tagi: #<Tag:0x00007f2adf658838> #<Tag:0x00007f2adf6584c8> #<Tag:0x00007f2adf6581f8>

image

Statyczny generator stron WWW - Hugo


Spis treści:

  1. Wstęp
  2. Instalacja Hugo
  3. Aktualizacja Hugo
  4. Szybki start, czyli stwórz swoją pierwszą stronę przy użyciu Hugo
    • Krok 1: Utworzenie strony
    • Krok 2: Dodanie motywu
    • Krok 3: Dodanie zawartości do naszej strony
    • Krok 4: Zbudowanie strony i uruchomienie serwera

1. Wstęp

Hugo jest statycznym generatorem stron HTML i CSS napisanym w aplikacji Go. Jest on zoptymalizowany pod kątem szybkości, łatwości obsługi i możliwości konfiguracji. Hugo pobiera katalog z treścią i szablonami i przekształca je w pełną stronę HTML.

Hugo polega na plikach Markdown z metadanymi, a Ty możesz uruchomić Hugo z dowolnego katalogu. Działa to dobrze w przypadku hostów współdzielonych i innych systemów, w których nie masz uprzywilejowanego konta.

Hugo w ułamku sekundy tworzy typową stronę internetową o umiarkowanym rozmiarze. Dobrą zasadą jest to, że każdy kawałek zawartości renderuje w około 1 milisekundę.

Hugo jest przeznaczony do pracy dla każdego rodzaju stron internetowych, w tym blogów, książek i dokumentów.


2. Instalacja Hugo

Gdy wstęp mamy za sobą zabierzmy się za to co najważniejsze, czyli instalację i konfigurację naszego Hugo

Instalacja międzyplatformowa

Instalacja między platformowa to ten typ instalacji, który wygląda tak samo dla wszystkich platform.
Aby dokonać takiej instalacji należy wejść na listę wersji projektu na GitHub, a następnie pobrać ją na swój serwer.

Najlepszym miejscem jest instalacja tego w miejscu gdzie kieruje zmienna PATH w Twoim systemie. W systemach linuxopodobnych najczęściej jest to /usr/local/bin.


Instalacja na Windows

Aby zainstalować na naszym Windowsie Hugo musimy zacząć od pobrania wybranej przez nas wersji (najlepiej najnowszej) na GitHubie projektu.

Gdy już pobierzemy wybraną przez nas wersję musimy stworzyć dla niej miejsce.
W naszym poradniku miejscem gdzie znajdować się będzie nasze Hugo jest C:\Hugo\bin, a więc zaczynamy od utworzenia tych folderów.

Na samym początku tworzymy folder Hugo na naszym Dysku podpisanym literką C:

image

Potem przechodzimy do naszego nowo utworzonego folderu i tworzymy w nim folder bin.

image

Następnie przechodzimy do folderu bin i przenosimy tutaj archiwum, które pobraliśmy przed chwilą.

image

Teraz wypakowujemy archiwum do aktualnego folderu.

image

Powinniśmy mieć takie pliki jak na obrazku powyżej. Jeśli tak jest możemy usunąć już nasze archiwum i tak o to zakończyliśmy instalację naszego Hugo w systemie Windows, lecz pozostaje nam jeszcze dodanie informacji o tym gdzie jest nasz framework do ścieżki PATH w naszym systemie.

Ustawienie zmiennej środowiskowej dla Hugo
  1. Kliknij prawym przyciskiem myszy na przycisk Start.
  2. Kliknąć na System.
  3. Kliknąć na Zaawansowane ustawienia systemowe po lewej stronie.
  4. Kliknąć na przycisk Zmienne środowiskowe… na dole.
  5. W sekcji Zmienne użytkownika znaleźć wiersz, który zaczyna się od PATH (PATH napisany CapsLockiem).
  6. Następnie wciskamy przycisk Nowa.
  7. W nowo otwartym oknie jako nazwę należy podać PATH, a w oknie wartości wybrać folder gdzie Twój Hugo został wypakowany, czyli według tego poradnika będzie to C:\Hugo\bin. Naciśnij Enter, gdy skończysz pisać.
  8. Kliknij OK w każdym oknie, aby wyjść.

Instalacja na Linux

W przypadku instalacji na Linux mamy do wyboru więcej opcji niż instalacja na Windows, zależnie od naszych upodobań i systemu możemy użyć domyślnego menadżera pakietów, snapa, czy homebrew.
W tej części poradnika zajmiemy się tylko dwoma pierwszymi opcjami.

Instalacja Hugo przez Snap

Jeśli chcemy by nasz Hugo mógł obsłużyć preprocesory CSS takie jak Sass czy SCSS potrzebujemy wersji rozszerzonej, możemy ją zainstalować poleceniem:

snap install hugo --channel=extended

Jeśli jednak nie potrzebujemy takich “bajerów” możemy użyć zwykłego polecenia:

snap install hugo

:warning: UWAGA WAŻNE!

Hugo zainstalowany za pośrednictwem Snapa może pisać tylko w katalogach $HOME i gvfs prowadzonych przez użytkownika, ponieważ Snaps jest zamknięty i zabezpieczony. Więcej informacji na ten temat znajduje się również w powiązanym wydaniu GitHuba.

Debian/Ubuntu

Jeśli korzystamy z systemów rodziny Debiana to dzięki uprzejmości użytkowników możemy zainstalować nasz framework jedną prostą komendą przy użyciu apt-get

sudo apt-get install hugo
Arch Linux

Jeśli korzystamy z systemu Arch Linux możemy skorzystać z polecenia pacman do instalacji Hugo:

sudo pacman -Syu hugo
CentOS, Fedora, Red Hat

Jeśli nasz wybór padł na systemy rodziny Red Hat Linux to Hugo zainstalujemy poleceniem:

sudo dnf install hugo
Solus

Solus posiada Hugo w swoich repozytoriach, więc instalacja będzie równie prosta:

sudo eopkg install hugo
OpenBSD

System OpenBSD również posiada w swoich repozytoriach Hugo, więc zainstalujemy go komendą:

doas pkg_add hugo


Instalacja na MacOS
Instalacja przez Homebrew

Naszym pierwszym krokiem będzie instalacja Homebrew jeśli go jeszcze nie mamy. (Jeśli masz już Homebrew możesz spokojnie przejść do następnego kroku)

Homebrew możemy zainstalować poleceniem:

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Następnie należy zainstalować Hugo poleceniem:

brew install hugo

Weryfikacja instalacji

W celu weryfikacji naszej instalacji wpiszmy w naszej konsoli polecenie:

hugo help

Jeśli w odpowiedzi dostaniemy coś w podobnieństwie do tego:

image

To znaczy, że poprawnie zainstalowaliśmy nasze Hugo!


3. Aktualizacja Hugo

Aktualizacja jest tak łatwa jak pobranie nowej paczki i podmiana plików wykonywalnych naszego Hugo.

Jeśli wykorzystaliśmy do instalacji Homebrew wystarczy użyć polecenia:

brew upgrade hugo

Zasada jest taka sama przy instalacji hugo z dowolnego innego menadżera pakietów.

Dla przykładu w systemach rodziny Debiana użyjemy polecenia:

apt-get upgrade hugo

4. Szybki start, czyli stwórz swoją pierwszą stronę przy użyciu Hugo

Krok 1: Utworzenie strony

W celu utworzenia nowej strony przy użyciu Hugo należy użyć polecenia:

hugo new site nazwa

Utworzy to w aktualnym folderze kolejny folder z plikami naszej strony. Dla celów poradnika użyjemy nazwy tutorial.

Więc zaczynamy od użycia naszego polecenia:

hugo new site tutorial

Krok 2: Dodanie motywu

Dla użytkowników GITa

Następnie musimy dodać nowy motyw do naszej strony. W tym wypadku użyjemy motywu ananke, więcej motywów możesz znaleźć tutaj.

Musimy przejść do naszego katalogu gdzie są pliki naszej strony, a następnie zaimportować do niej nasz motyw.

Użyjemy do tego następujących poleceń:

//Przejście do katalogu
cd tutorial
//Zainicjowanie i dodanie modułu motywu do naszej strony
git init
git submodule add https://github.com/budparr/gohugo-theme-ananke.git themes/ananke

Gotowe! Nasz motyw został dodany i może być wykorzystany na naszej stronie.

Dla użytkowników nie posiadających GITa

Najpierw musisz zacząć od pobrania archiwum naszego motywu ze strony https://github.com/budparr/gohugo-theme-ananke/archive/master.zip

Następnie należy wypakować nasze archiwum, a wynikiem tej operacji będzie folder gohugo-theme-ananke-master.

Następnym i ostatnim krokiem będzie zmiana nazwy folderu z gohugo-theme-ananke-master na ananke oraz przeniesienie go do katalogu themes w folderze naszej utworzonej strony.

Zmiana motywu na stronie

Zmiana motywu to to samo co zmiana linijki theme = xxxx w pliku config.toml. Możemy to zrobić bezpośrednio z poziomu terminala używając polecenia:

echo 'theme = "ananke"' >> config.toml

:warning: UWAGA

W systemie Windows w moim przypadku trzeba usunąć ' z polecenia, gdyż spowoduje to potem błędy w konfiguracji i nie pozwoli na uruchomienie serwera!

Krok 3: Dodanie zawartości do naszej strony

Gdy już utworzyliśmy naszą stronę oraz dodaliśmy motyw przydałoby się stworzyć troche zawartości, prawda?

Użyjemy do tego polecenia:

hugo new posts/firstpost.md

:warning: UWAGA

Przy tworzeniu nasz post jest tworzony jako szkic. Domyślnie szkic nie jest brany pod uwagę przy budowaniu strony, aby to zmienić należy zmienić w ustawieniach naszego posta linijkę draft: true na draft: false.

W wyniku tego polecenia utworzony zostanie plik z naszym postem (np. na bloga). Wygląda on mniej więcej tak:

---
title: "Firstpost"
date: 2020-05-22T02:31:08+02:00
draft: true
---

Nasz utworzony post zaczyna się od linijki ustawień, gdzie:

title - jest to tytuł naszego posta

date - jest to data utworzenia naszego posta

draft - jest to zmienna, która mówi czy dany post jest jeszcze szkicem. Jeśli ukończymy nasz post należy zmienić to z false na true, gdyż inaczej nie zostanie on przetworzony przy włączaniu serwera i będzie niedostępny.

Poniżej ustawień możemy umieścić naszą zawartość przy użyciu np. Markdown.

Krok 4: Zbudowanie statycznych plików

Teraz przydałoby się, aby można było zobaczyć owoce naszej pracy poprzez zbudowanie naszych statycznych plików, które zostaną utworzone w katalogu public w głównym folderze naszej strony. Będziemy mogli później użyć tych plików przy pomocy serwera WWW takiego jak np. nginx czy apache2.

Użyjmy do tego polecenia:

hugo

Jeśli chcemy zbudować także posty oznaczone jako szkic użyjemy polecenia:

hugo -D

Krok 5: Zbudowanie strony i uruchomienie serwera (Opcjonalne)

:warning: UWAGA

Przy uruchomieniu serwera publicznie należy pamiętać o włączeniu go przy pomocy narzędzi takich jak screen czy tmux, aby uniknąć wyłączenia się serwera przy zamknięciu terminala.

Po tym jak utworzyliśmy stronę, dodaliśmy motyw oraz zawartość przyszła pora, aby móc zobaczyć naszą pracę.

Należy uruchomić serwer poleceniem:

hugo server

Opcjonalnie możemy uruchomić nasz serwer na przykład tak, aby zbudował także zawartość oznaczoną jako szkic (draft) używając polecenia:

hugo server -D

W odpowiedzi otrzymamy uruchomiony proces serwera z informacją na jakim adresie i porcie nasłuchuje.


5. Deployment strony, czyli niech zobaczy nas świat

Nasza zbudowana strona wymaga jednak jeszcze kilku rzeczy, a wśród nich jest serwer WWW, który obsłuży nasz ruch i pokaże innym dzieło naszej pracy.

Wybór jest spory, lecz dla tego poradnika użyjemy Linuxa w dystrybucji Ubuntu 20.04 i serwera WWW obsługiwanego przez nginx.Dlaczego nginx? Moim zdaniem będzie lepszy dla statycznych plików i lepiej przygotowany do obsłużenia większego ruchu, co może okazać się bardzo przydatne, gdy ktoś zechce zepsuć nam humor i próbować ataków na naszą stronę WWW.

:warning: UWAGA

W tym miejscu, jeśli nie wiesz czym jest domena, serwer WWW, czy VirtualHost to muszę Cię zaprosić do zapoznania się z innymi poradnikami na forum, aby zrozumieć tą część w pełni.

Dla tej części poradnika musimy przyjąć kilka ważnych wiadomości, aby dobrze go zrozumieć:

  • System, którego używamy to Linux w dystrybucji Ubuntu 20.04
  • Przyjmujemy, że nasza strona, którą utworzyliśmy nazywa się przyklad.pl i jest umieszczona w katalogu /var/www, czyli nasza strona sama w sobie znajduje się w /var/www/przyklad.pl.

Krok 1: Instalacja nginx

Aby zainstalować nginx musimy użyć prostego polecenia

apt install nginx

Akceptujemy instalację, gdy nas o to zapyta i czekamy chwilę na zakończenie instalacji.

Krok 2: Konfiguracja vHost (wirtualny host) dla naszej strony

Następnym krokiem jest poinformowanie naszego serwera WWW, na jakim porcie, domenie ma odpowiadać i gdzie ma szukać plików naszej strony. Zrobimy to przez utworzenie wirtualnego hosta dla naszego serwera WWW.

Przykładowy wirtualny host wygląda podobnie do tego:

server {
        listen 80 default_server;
        listen [::]:80 default_server;

        root /var/www/html;
        index index.html index.htm index.nginx-debian.html;

        server_name _;

        location / {
                try_files $uri $uri/ =404;
        }
}

Musimy go przerobić, aby mógł obsłużyć naszą stronę poprawnie. Więc bierzmy się do pracy:

Zaczynamy od otworzenia edytora, w którym będziemy mogli dodać naszą zawartość. Nazwa pliku będzie odpowiadać nazwie naszej strony, czyli w tym przypadku przyklad.pl, a sam plik utworzymy w katalogu, gdzie znajdują się pliki konfiguracyjne serwera WWW i folderze nazwanym sites-available.

Otwieramy nasz plik przez edytor nano poleceniem:

sudo nano /etc/nginx/sites-available/przyklad.pl

Teraz musimy utworzyć nasz VirtualHost, więc zróbmy to dodając do naszego pliku dane:

server {
  listen 80; #Informujemy na jakim porcie ma odpowiadać nasza strona dla interfejsu IPv4
  listen [::]:80; #Informujemy na jakim porcie ma odpowiadać nasza strona dla interfejsu IPv6

  root /var/www/przyklad.pl/public; # Informujemy gdzie zbudowane znajdują się pliki naszej strony

  server_name przyklad.pl; #Informujemy serwer na jakiej domenie ma odpowiadać nasza strona, gdy jej nie mamy i chcemy, aby adres IP odpowiadal naszej stronie uzywamy `_` zamiast domeny

  location / {
                try_files $uri $uri/ =404;
  }
}

Następnie sprawdzamy poprawność naszego wirtualnego hosta poleceniem:

nginx -t

Jak widać nginx mówi, że wszystko jest poprawne, więc możemy przejść dalej.

Krok 3: Przeładowanie plików konfiguracyjnych nginx

:warning: UWAGA

Przy każdej zmianie w plikach konfiguracyjnych serwera WWW należy ponownie przeładować pliki konfiguracyjne. Dobrym nawykiem może też być sprawdzanie po każdej większej zmianie poprawności konfiguracji, aby nie być zaskoczonym, że strona przestała działać lub działa niepoprawnie.

Na koniec została nam tylko jedna czynność - przeładowanie plików konfiguracyjnych nginx.

W aktualnej sytuacji zrobimy to przy użyciu polecenia:

systemctl reload nginx

I gotowe! Właśnie wystawiłeś swoją stronę na światło dziennie i Ty jak i inni użytkownicy możecie podziwiać dzieło Twojej pracy.


6. Zakończenie

Trochę pracy kosztowało przygotowanie tego poradnika, sporo myślenia nad wyglądem, układem, sporo pracy redakcyjnej w postaci pisania, sprawdzania i redagowania na nowo części, które uznałem, że są zbyt długie, zbyt krótkie lub zbyt skomplikowane. Można się poczuć trochę jak pracownik jakiegoś magazynu, który zajmuje się sprawami technicznymi, fajnie tak.

Ale przechodząc do sedna mam nadzieję, że taka forma poradnika jest dla Was zrozumiała i dogłębnie tłumaczy podstawy korzystania z Hugo, który jest znacznie bardziej zaawansowany i zostało mi więcej do opisania, lecz jest to już dla użytkowników bardziej zaawansowanych.

Zadaniem tego poradnika było jedynie wprowadzenie w świat tego frameworka, lecz myślę, że zachęci to Was do uczenia się coraz więcej o nim, tak jak mnie zachęciło do tego pisanie tego poradnika.


Źródła:


1lajk

Instalacja na MacOS się nie rozwija :crying_cat_face:

I w zasadzie opisałeś tylko instalacje, nic więcej.

Czekam na dalsze aktualizacje poradnika, bardzo podoba mi się przejrzystość spisu treści z odnośnikami. To coś, co koniecznie muszę zaaplikować też do moich poradników. Poza tym dobry opis czym Hugo jest, ale resztę tak naprawdę dopiero będzie można ocenić jak dodasz najistotniejsze kwestie dotyczące instalacji. Pytałeś w innym wątku o kwestie wizualne - są świetne, kontynuować to w tym kierunku. :star_struck:

Dlatego, że moim planem było podzielenie tego na kilka części, aby łatwiej było działać na treści. Niestety Discourse ma trochę więcej niż czysty Markdown, a żeby widzieć zmiany muszą być pisane w oknie tworzenia posta. Niestety przy dużej ilości tekstu staje się to strasznie nieczytelne, a nawet kilka razy przy próbie robienia kopiuj - wklej z innego programu (np. VS Code) zdażało się, że było to źle odczytywane. Tak samo z obrazkami, których nie dodam w innym programie, gdyż musiałaby być na zewnętrznym hostingu.

//Edit:

Specjalnie dla Ciebie Artur dopisałem pierwszy sposób instalacji na macOS, lecz nie jestem w stanie sprawdzić w 100% jego poprawności tak jak w przypadku innych sposobów, więc posłużyłem się tylko tekstem z dokumentacji Hugo.

Wygląda ok, w wolnej chwili spróbuje sobie go zainsalować i ci po prostu powiem czy działa.

zapowiada się ciekawie

Aktualizacja poradnika

Dodałem resztę rzeczy wymaganych do uruchomienia pierwszej strony przy pomocy Hugo, więc zachęcam do sprawdzenia.


W planach jest jeszcze:

  • dokończenie informacji o instalacji na macOS
  • pokazanie uruchomienia automatycznego budowania od nowa plików przy zmianach w naszych plikach
  • krótki spolszczony opis wszystkich dodatkowych parametrów, które maja pomóc w ogarnięciu co, gdzie i dlaczego
  • (bym zapomniał :joy:) dokończenie spisu treści

Super :grinning: tylko jedna uwaga, nie wiem czy słuszna. Czytałam gdzieś, że instalacja za pomocą apt-get daje starszą wersję od razu. Lepsze jest pobranie archiwum i instalacja z niego. Podobno. A już najwygodniej ze snapa :grinning:

Istnieje taka szansa, gdyż u mnie jest zainstalowana wersja 0.68 pobrana przez APT, z tego co wyczytałem SNAP ma tą wadę, że dostęp do plików nie jest ogólny i jest to zamknięte przez snap.

Ale jak rozumiem wszystko mogę robić tak jak napisałeś w poradniku uprzednio Instalując ze snapa? Snap instaluje mi bloga w root. Czy to ma znaczenie w jakim folderze zainstaluję hugo? Czy lepiej na przykład zainstalować w /home?

Cytując dokumentację

Hugo zainstalowany za pośrednictwem Snapa może pisać tylko w katalogach $HOME i gvfs prowadzonych przez użytkownika, ponieważ Snaps jest zamknięty i zabezpieczony. Więcej informacji na ten temat znajduje się również w powiązanym wydaniu GitHuba.

Możesz zrobić wszystko odpowiednio korzystając ze snapa, lecz wtedy trzeba wziąć pod uwagę powyższe ograniczenie.

Różnica między instalacja w np. /bin (lub innym) a instalacji w katalogu domowym użytkownika nie zmienia nic oprócz dostępu do Hugo. Wtedy jest on dostępny tylko dla roota i tego użytkownika (jeśli nie zmienialiśmy nic be uprawnieniach)