Generatorzy statycznych stron od zera: słownictwo, historia i pierwsze utworzenie strony
Przyswoić terminy, które według dokumentacji SSG zakłada się, że znasz, zrozumieć, jak ze sobą łączą się układy strony, części dodatkowe i elementy wstępne, skąd pochodzą generatorzy oraz jak wybrać jeden bez problemów.
Generatorzy stron statycznych obiecują prostą rozwiązanie: pisz wpisy w formacie Markdown, przechowuj nagłówek i stopkę w jednym miejscu, a otrzymasz szybką stronę internetową składającą się z zwykłych plików. Dla wielu początkujących rzeczywistość wygląda jednak jak ściana niezrozumiałego żargonu, terminal wyświetlający ścieżki stosu oraz dokumentacja zakładająca lata wiedzy przedmiotowej. Ten przewodnik eliminuje tę lukę od podstaw. Dowiesz się, jakie umiejętności należy posiadać przed rozpoczęciem pracy, co faktycznie oznacza każdy powtarzający się termin w dokumentacji generatora, jak ze sobą łączą się elementy typowego projektu Eleventy, skąd pochodzą te narzędzia oraz jakie lżejsze alternatywy istnieją, gdy popularne rozwiązania wydają się zbyt skomplikowane.
Zanim wybierzesz generator: niezbędne umiejętności
Generator stron statycznych (SSG) to warstwa abstrakcji nad stronami internetowymi. Jeśli nigdy nie tworzyłeś strony ręcznie, ta abstrakcja ukrywa dokładnie te elementy, które musisz zrozumieć, gdy coś pójdzie nie tak. Przy pierwszych kilku stronach lepszym sposobem na naukę jest samodzielne pisanie kodu HTML i CSS. Doświadczysz trudności z kopiowaniem tej samej nawigacji do dziesięciu plików, a właśnie te trudności sprawią, że później docenisz funkcjonalność generatora.
Prawie każdy generator zakłada, że znasz HTML i CSS, często także podstawy JavaScripta, ogólne zasady programowania takie jak zmienne i pętle, pole komend oraz zazwyczaj Git. Nikt nie musi najpierw opanować wszystkich tych umiejętności. Chodzi o to, że podstawowy model mentalny każdej warstwy przekształca niezrozumiałe błędy podczas budowania strony w problem, który da się rozwiązać, zamiast w tajemnicę.
Ścieżka nauki z darmowych zasobów
Następujące zasoby sprawdzają się najlepiej mniej więcej w tej kolejności. Twórz małe strony tymczasowe w miarę postępów, zamiast traktować tę listę jako zadanie domowe do ukończenia najpierw.
- HTML: Książka „HTML for People” jest napisana dla osób bez żadnego doświadczenia w programowaniu. Jeśli chcesz dowiedzieć się więcej na temat elementów semantycznych i dostępności, przejdź do modułu MDN poświęconego strukturyzacji treści.
- CSS: Moduł MDN dotyczący podstaw stylizacji omawia koncepcje takie jak model pudełka i układ. Jeśli bardziej odpowiadają ci ćwiczenia praktyczne, kurs freeCodeCamp na temat projektowania responsywnego omawia HTML, CSS, dostępność oraz projektowanie responsywne (w praktyce przyjazne urządzeniom mobilnym).
- JavaScript: Moduł MDN poświęcony skryptowaniu naturalnie kontynuuje materiały z dziedziny HTML i CSS, a program nauczania JavaScript od freeCodeCamp stanowi interaktywną alternatywę.
Jeśli wolisz jedno centralne źródło informacji zamiast zbioru różnych materiałów, obszar edukacyjny MDN obejmuje HTML, CSS, JavaScript oraz podstawy przeglądarek w ramach jednego programu nauczania. Innymi opcjami są web.dev, The Odin Project i w3schools.
Pamiętaj o perspektywie: osobista strona internetowa to zazwyczaj projekt hobby. Nietypowe rozwiązania i błędy są częścią procesu, a każda ukończona mała strona dodaje nową umiejętność, którą możesz wykorzystać przy tworzeniu następnej.
Słownictwo, którego według dokumentacji static-site zakłada się znajomość
Dokumentacja generatorów często używa tuzina terminów, jakby wszyscy poznali je od urodzenia. W tej sekcji terminy te są definiowane prostym językiem, a każdy z nich pokazany jest w małym, konkretnym pliku z projektu Eleventy (11ty).
Markup, styl i zachowanie: HTML, CSS i JavaScript
HTML (HyperText Markup Language) opisuje strukturę i znaczenie dokumentu: nagłówki, akapity, linki, obrazy, listy. Nie jest językiem programowania. Nie może podejmować decyzji ani niczego powtarzać samodzielnie; po prostu określa, co znajduje się na stronie. Najmniejsza użyteczna strona składa się z doctype, tagu <head> zawierającego zbiór znaków i tytuł oraz tagu <body> z treścią. Należy zauważyć, że nic tutaj nie kontroluje kolorów ani czcionek, więc przeglądarka używa swoich domyślnych stylów.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>My First Page</title>
</head>
<body>
<h1>Hello, world!</h1>
<p>This page has a <a href="https://brennan.day">link</a> and a list:</p>
<ul>
<li>HTML gives a page its structure.</li>
<li>There's no CSS yet, so this is all default styling.</li>
</ul>
</body>
</html>Copy
Zapisanie tego pliku jako index.html i otwarcie go w dowolnej przeglądarce daje dostęp do działającej strony internetowej – nie jest potrzebny żaden serwer. (Słowo Copy po zamkniętym tagu to pozostałość po przycisku kopiowania i nie stanowi części kodu strony.)
CSS (Cascading Style Sheets) określa, w jaki sposób prezentowana jest ta struktura: kolory, odstępy, typografia oraz to, jak układ dostosowuje się do różnych rozdzielczości ekranów. Poniższe zasady ustawiają czcionkę z serifem, ograniczają szerokość tekstu, aby wiersze były czytelne, centrują kolumnę z automatycznymi marginesami oraz nadają stronie ciepły tło i ciemne kolory tekstu. Tytuł ma własną zasadę dotyczącą koloru.
body {
font-family: Georgia, serif;
max-width: 35rem;
margin: 2rem auto;
padding: 0 1rem;
background: #fff2ce;
color: #02005d;
}
h1 {
color: rebeccapurple;
}Copy
Umieszczenie tych zasad w elemencie <style> w sekcji <head> wcześniejszej strony zmienia jej wygląd bez konieczności modyfikowania ani jednego słowa w kodzie HTML. To oddzielenie treści od prezentacji jest cechą charakterystyczną wszystkich generatorów stron statycznych.
JavaScript to język programowania, którym działają przeglądarki. Dodaje on funkcjonalności: reagowanie na kliknięcia, zmianę treści, pobieranie danych. Jest również najprostszym sposobem na sprawienie, że prosta strona stanie się ciężka i wolna, dlatego dobrym standardem dla strony osobistej jest używanie go tylko tam, gdzie faktycznie ma sens. Poniższy fragment znajduje element o identyfikatorze surprise, nasłuchuje kliknięć w nim i zastępuje tekst pierwszego elementu <h1> po wystąpieniu kliknięcia.
const button = document.querySelector("#surprise");
button.addEventListener("click", () => {
document.querySelector("h1").textContent = "JavaScript did this!";
});Copy
Aby to zadziałało, strona musi zawierać odpowiadający element <button id="surprise">. Bez niego funkcja querySelector zwraca null, a wywołanie addEventListener powoduje błąd, co jest częstym pierwszym problemem.
JavaScript występuje również po stronie generatora, a nie tylko w przeglądarce. Wiele narzędzi typu SSG jest napisanych w JavaScript i wykorzystuje go do uruchamiania procesu budowania lub ewaluacji szablonów. Eleventy nawet pozwala, aby cały szablon stanowił plik JavaScript – treścią strony staje się dowolna ciąg znaków zwrócony przez eksportowaną funkcję.
// hello.11ty.js
module.exports = function () {
return "<h1>Hello from JavaScript!</h1>";
};Copy
W tym przykładzie użyto CommonJS module.exports. Nowsze wersje Eleventy obsługują również składnię modułów ES (export default), więc sprawdź, który styl jest używany w dokumentacji do Twojej zainstalowanej wersji.
Co tak naprawdę oznaczają „static”, „build” i „output”
- Statyczny opisuje sposób dostarczania treści: serwer przekazuje plik dokładnie tak, jak jest przechowywany, zamiast tworzyć nową odpowiedź dla każdego odwiedzającego. Strona statyczna może nadal zawierać JavaScript i można ją edytować oraz ponownie wdrożyć. Nie oznacza to jednak, że jest nudna lub zamrożona na zawsze.
- Dynamiczny oznacza, że odpowiedź jest obliczana w momencie żądania. Klasyczny system zarządzania treścią wysyła zapytanie do bazy danych i komponuje stronę przy każdym odwiedzeniu. Klasycznym przykładem jest sklep internetowy, ponieważ stan zapasów i koszyki zakupowe ciągle się zmieniają.
- Generator stron statycznych to program, który odczytuje materiały źródłowe (treści w formacie Markdown, szablony, konfigurację, obrazy oraz inne zasoby) i tworzy gotowe pliki HTML, CSS, JavaScript oraz obrazów, które może serwować każdy host obsługujący strony statyczne.
_site/, public/ lub dist/. Zazwyczaj nie edytuje się ich ręcznie, ponieważ kolejna budowa je nadpisuje.localhost:8000 i często automatycznie ponawia budowę po zapisaniu pliku źródłowego.Pliki konfiguracyjne i dane strony
- Plik konfiguracyjny zawiera ustawienia dotyczące całego strony, takie jak nazwa strony, podstawa URL, menu, katalog wyjściowy lub opcje feedów. Nazwy i formaty różnią się w zależności od narzędzia:
config.yml,hugo.toml,eleventy.config.jsi inne. - YAML to przyjazny dla człowieka format danych powszechnie używany w konfiguracjach i treściach wstępnych. Pozwala na reprezentację ciągów znaków, liczb, list oraz par klucz-wartość. Występowanie odstępów ma znaczenie, więc jeden błędnie umieszczony przecinek może spowodować awarię procesu budowania.
- Para klucz-wartość to ustawienie składające się z nazwy i wartości, na przykład
title: Moja publikacja. W YAML grupa takich par nazywana jest mapowaniem. - Parametr lub opcja to ustawienie, które przekazuje się do polecenia lub umieszcza w pliku. Przykładem może być flaga
--serve, z którą spotkasz się później.
W Eleventy pliki w folderze _data stają się danymi globalnymi dostępnymi dla każdego szablonu. Plik src/_data/site.json przechowuje informacje widoczne dla odwiedzających: nazwę strony, krótki opis, autora, publiczną adres URL oraz język.
{
"name": "My Cool Blog",
"description": "Where I write about whatever interests me.",
"author": "Your Name",
"url": "https://example.com",
"language": "en"
}
Każda kluczowa wartość staje się zmienną szablonu. Układ zawierający {{ site.name }} wyświetla wartość „My Cool Blog”, więc zmiana nazwy strony oznacza edycję jednej linijki tutaj, zamiast przeszukiwania każdej strony. Jekyll przechowuje podobne informacje w pliku config.yml, a Hugo w pliku hugo.toml; idea jest identyczna, zmienia się tylko plik. Należy pamiętać, że JSON jest rygorystyczny: przecinek po ostatniej pozycji stanowi błąd składniowy, co okazuje się ważne później w tym przewodniku.
Układy, fragmenty i szablony
- Śablon to plik wielokrotnego użycia, który określa strukturę strony i zawiera miejsca zastąpień dla elementów, które się zmieniają.
- Rozkład to śablon całej strony: deklaracja języka, tag
<head>, nagłówek, główna obszara treści oraz stopka. - Część to mały fragment wielokrotnego użycia, taki jak pasek nawigacyjny, stopka lub blok metadanych posta. Include to instrukcja, która włącza jeden fragment do innego pliku.
- Język szablonów to składnia służąca do wyświetlania zmiennych, przetwarzania danych w pętlach oraz podejmowania decyzji w śablonach. Powszechnymi przykładami są Liquid, Nunjucks i Go templates.
- Warunkowy to reguła typu „tak albo nie” w śablonie, na przykład „wyświetlć obraz główny tylko wtedy, gdy post zawiera taki element”.
Bazowy layout poniżej, _includes/layouts/base.njk, jest napisany w Nunjucks. Tytuł łączy własny tytuł strony z globalną nazwą strony, dwie tagi include wstawiają fragmenty nagłówka i stopki, a renderowana treść strony jest wyświetlana wewnątrz <main>.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>{{ title }} | {{ site.name }}</title>
</head>
<body>
{% include "partials/header.njk" %}
<main>
{{ content | safe }}
</main>
{% include "partials/footer.njk" %}
</body>
</html>
Filtr | safe jest istotny. Nunjucks domyślnie escapeuje wyjście, co sprawiłoby, że HTML posta zamieniłby się w widoczne tagi. Oznaczenie content jako bezpiecznego informuje silnik, że ta strona jest wiarygodna i stanowi już renderowany HTML. Używaj go tylko dla treści, nad którymi masz kontrolę.
Samych fragmentów składowych są zwykłe fragmenty HTML, które mogą wykorzystywać zmienne i zawierać dodatkowe fragmenty. Nagłówek odwołuje się do strony głównej za pomocą nazwy strony i ładuje menu nawigacyjne; menu to zwykła lista linków; stopka wyświetla informację o prawach autorskich wraz z imieniem autora z danych strony.
<!-- partials/header.njk -->
<header>
<a href="/">{{ site.name }}</a>
{% include "partials/nav.njk" %}
</header>
<!-- partials/nav.njk -->
<nav>
<a href="/">Home</a>
<a href="/archive/">Archive</a>
<a href="/about/">About</a>
</nav>
<!-- partials/footer.njk -->
<footer>
<p>© 2026 {{ site.author }}</p>
</footer>
Oto jak te elementy się łączą. Gdy post zawiera w swoim front matterze informację layout: base.njk, Eleventy renderuje ten post, a następnie umieszcza wynik w miejscu, gdzie znajduje się {{ content | safe }} w szablonie, przy czym każdy tag include jest zastępowany odpowiednim fragmentem składowym. Zmieniając menu nawigacyjne raz, każda strona na stronie przy następnej kompilacji przejmie tę zmianę. Usunięcie konieczności ręcznego kopiowania i wklejania to główny powód istnienia SSG. Jest jednak jedna mała uwaga: rok w stopce jest ustawiony sztywno, więc nie będzie się aktualizował, chyba że zastąpisz go zmienną.
Pliki z treścią, Markdown i front matter
- Plik z treścią to plik źródłowy strony lub wpisu. Najczęściej używanym formatem jest Markdown, ale wiele generatorów akceptuje również HTML, zwykły tekst lub inne formaty.
- Markdown to lekki język znaczników, w którym interpunkcja służy do określania struktury:
#dla nagłówków, gwiazdki do podkreślenia, myśliwy do tworzenia list. Generator przekształca go na HTML. - Front matter to blok metadanych umieszczony na samym początku pliku z treścią, zwykle otoczony dwiema liniami składającymi się z trzech myśliwych. Może zawierać tytuł, datę, tagi, nazwę układu lub flagę wersji roboczej.
- Metadane to informacje opisowe dotyczące treści: tytuł, autor, data publikacji, tagi, opis, URL kanoniczny lub wybrany układ.
Plik posts/my-first-post.md poniżej łączy wszystko to w jedno. Front matter w formacie YAML określa tytuł, datę, dwa tagi, układ oraz flagę wersji roboczej. Treść łączy zwykły Markdown z składnią szablonów w stylu Nunjucks, która wyświetla tytuł i warunkowo pokazuje zdanie.
---
title: My First Post
date: 2026-09-22
tags:
- posts
- cats
layout: post.njk
draft: false
---
Welcome to my blog! This paragraph is **Markdown**.
This post is called "{{ title }}".
{% if draft %}
This sentence only appears while the post is a draft.
{% endif %}
Eleventy czyta treść wstępną przed wyświetleniem jakiegokolwiek zawartości. Klucz layout wybiera szablon otaczający treść, tag posts dodaje plik do kolekcji o nazwie posts (którą strona archiwum może przeglądać), a date określa kolejność sortowania z uwzględnieniem daty publikacji. Wszystko po zamkniętych cudzysłowach stanowi treść główną. Ponieważ wartość draft jest tutaj false, zdanie warunkowe nie pojawia się w wyniku. Należy pamiętać, że klucz draft nie ma wbudowanego znaczenia w Eleventy; wykluczanie wersji roboczych z budowy produktowej to kwestia, którą konfiguruje się samodzielnie.
Hosting, serwery tła i warunki wdrażania
- Hosting to usługa lub maszyna, która przechowuje pliki wygenerowane przez stronicę i umożliwia ich dostęp w Internecie. Jest to kwestia odrębna od pisania samej strony oraz od zarządzania wersjami.
Kontrola wersji na jednej stronie
- Kontrola wersji rejestruje zmiany w plikach na przestrzeni czasu, dzięki czemu można przejrzeć historię, porównywać wersje, cofać zmiany i współpracować.
- Git to konkretny program do kontroli wersji. Działa wyłącznie na twoim komputerze i nie wymaga żadnej usługi online do śledzenia historii.
- Repozytorium to folder projektu, którego historię zarządza Git.
- Commit to zapisany obraz zmian, zwykle wraz z komunikatem opisującym je.
- Remote to kolejna kopia repozytorium, często hostowana na Codebergu, GitHubie, GitLabie lub twoim własnym serwerze.
- Push wysyła twoje lokalne komitety na serwer zdalny; pull pobiera komitety z serwera zdalnego i łączy je z twoją lokalną kopią.
- Usługi hostingu Git przechowują repozytoria i często dodają funkcje śledzenia problemów, przeglądania kodu oraz automatycznych budowań. Są wygodne, ale nie stanowią samego Gitu, a Git funkcjonuje bez nich prawidłowo.
Opublikowanie nowego posta za pomocą Git z terminala wymaga czterech poleceń. Pierwsze jest wykonywane tylko raz na projekt; pozostałe trzy to codzienna procedura przygotowania pliku do publikacji, zapisania jego kopii oraz wysłania jej na serwer zdalny.
git init # turn this folder into a repository (once)
git add posts/new-post.md # stage the file for your next commit
git commit -m "Add new post" # save a snapshot with a message
git push # copy your commits to the remoteCopy
W praktyce git push działa tylko po skonfigurowaniu zdalnego repozytorium, na przykład za pomocą git remote add origin <url>, a pierwsze wysłanie zmian z gałęzi zazwyczaj wymaga użycia git push -u origin main lub podobnego polecenia. Gdy to zostanie ustawione, wystarczy zwykłe git push.
Pochodzenie generatorów stron statycznych
Gdy już mamy odpowiednią terminologię, historia staje się bardziej zrozumiała, ponieważ każda nowa generacja narzędzi dodawała jeden z powyższych koncepcji.
Rozdzielenie procesu pisania od formatowania treści istniało na długo przed pojawieniem się terminu „generator stron statycznych”. HSC, skrót od „HTML Sucks Completely”, to preprocesor HTML stworzony przez Thomasa Aglassingera w 1996 roku. Już wtedy oferował funkcje takie jak include’i, warunki oraz walidację linków, około dekady przed tym, jak ta kategoria otrzymała nazwę.
Przez koniec lat 90. i lata 2000. większość osób chcących mieć blog wybierała hostowane, dynamiczne usługi takie jak Blogger, LiveJournal czy Open Diary, albo instalowała oprogramowanie oparte na bazie danych, np. WordPress. Movable Type – platforma napisana w języku Perl przez Bena i Menę Trottów w 2001 roku – obrała inną drogę: za każdym razem, gdy publikowano treści przez jej interfejs internetowy, blog był przekształcany na zwykłe pliki HTML statyczne. Użytkownicy nigdy nie korzystali z terminala, a mimo to czytelnicy otrzymywali strony statyczne. Dzięki temu osoby, które nigdy nie wpisałyby polecenia budowania, mogły korzystać z zalet wyjścia w formie plików statycznych.
Nanoc pojawił się w 2007 roku, stworzony przez Denisa Defreyne’a po tym, jak systemy zarządzania treścią typu Ruby okazały się zbyt wolne na jego wirtualnym serwerze o pojemności 96 MB. Wprowadził on układy strony, metadane na poziomie poszczególnych stron, obsługę Markdown oraz wtyczki. W grudniu 2008 roku współzałożyciel GitHuba, Tom Preston-Werner, wydał Jekyll, motywowany niezadowoleniem z ciężkich silników do tworzenia blogów. Jekyll opierał się na ideach Nanoc i dodał dwie kluczowe cechy: YAML front matter na początku każdego pliku z treścią oraz natychmiastową funkcjonalność blogową, dzięki czemu folder z plikami Markdown stawał się blogiem bez dodatkowej konfiguracji. Równocześnie uruchomiono GitHub Pages jako bezpłatne hostowanie statyczne, a to połączenie bardziej niż cokolwiek innego przyczyniło się do upowszechnienia SSG.
Prawie wszystko, co powstało później, to reinterpretacja tego samego wzorca w innych językach. Octopress, który obecnie nie jest już dostępny, oraz Middleman kontynuowały linię rozwoju narzędzi opartych na Ruby. Pelican jest zbudowany na bazie Pythona, natomiast Hyde opiera się na Laravel.
Steve Francia w lipcu 2013 roku stworzył Hugo – program napisany w języku Go, dostępny jako pojedynczy zbiór skompilowanych plików binarnych. W porównaniu z Jekyll nie wymagał instalacji środowiska Ruby ani dostosowywania wersji gemów, a jego szybkość kompilacji, mierzona w sekundach nawet dla stron z tysiącami stron, stała się jego główną cechą wyróżniającą.
Później, w 2017 roku, Zach Leatherman wydał Eleventy (11ty) – elastyczną alternatywę dla Jekyll, która działa na JavaScript i instaluje się za pomocą npm. Jekyll wiąże użytkownika z językiem Liquid, natomiast Eleventy obsługuje szeroki wybór formatów szablonów:
- formatowanie i treść: zwykły HTML (
.html), Markdown (.md) oraz MDX (.mdx)
.11ty.js, TypeScript (.ts), JSX (.jsx) oraz WebC (.webc).njk), Handlebars (.hbs), Mustache, EJS, Haml i Pug.scss)Część z tych formatów wymaga dodatkowego pluginu lub konfiguracji, aby działać bez żadnych modyfikacji, dlatego przed ich użyciem sprawdź aktualną dokumentację Eleventy. Jeśli znasz już konkretny język programowania, katalog generatorów na stronie Jamstack.org umożliwia filtrowanie narzędzi napisanych w tym języku.
Wiele generatorów w tym katalogu nie miało nowej wersji od lat, a dla strony osobistej jest to często do przyjęcia. Strona statyczna nie ma kodu po stronie serwera ani bazy danych dostępnych dla odwiedzających, co eliminuje najczęstsze źródła ataków w blogach dynamicznych. Jeśli nowa wersja twojego generatora dodaje funkcje, których nie lubisz, możesz nadal używać starej wersji – ona będzie nadal tworzyć tę samą stronę. Należy jednak pamiętać, że „brak aktualizacji” nie oznacza „braku ryzyka”: zależności używane podczas budowania, maszyna, na której odbywa się proces budowania, oraz wszelkie zewnętrzne pliki JavaScript nadal wymagają uwagi, a narzędzie niewartowane dalszej obsługi może z czasem przestać prawidłowo instalować się na nowszym systemie operacyjnym lub środowisku językowym.
Git rozwiązuje dwa problemy, a ty nie potrzebujesz żadnego z nich
Przewodniki dla początkujących niemal zawsze radzą korzystać z Git. Częściowo wynika to po prostu ze zwyczaju wśród programistów, ale częściowo ma podłoże historyczne: Jekyll, pierwszy powszechnie stosowany SSG, powstał jako projekt na GitHubie. Hostowanie na GitHubie, Codebergu lub GitLabie odpowiada na pytanie „gdzie znajdują się moje pliki?” odpowiedzią „w repozytorium”. Usługi takie jak Neocities czy Nekoweb odpowiadają na to inaczej – pliki przesyła się przez samą stronę.
W usługach hostingu opartych na Git, takich jak Codeberg Pages czy GitLab Pages, nawet edycje dokonane w interfejsie internetowym stają się komitami i są wysyłane w tle. Korzystasz z Git, niezależnie od tego, czy kiedykolwiek wpiszesz jakiś polecenie Git.
Jeśli sam hostujesz stronę, pliki znajdują się na twoim własnym komputerze, zazwyczaj w katalogu takim jak /var/www/html w systemie Linux. Na współdzielonym serwerze społecznościowym, np. Tildeverse, pliki te znajdują się w publicznym folderze twojego konta; powszechną praktyką jest tworzenie plików lokalnie, a następnie użycie rsync do skopiowania ich na serwer współdzielony, gdzie są automatycznie serwowane.
W takich konfiguracjach pomocne jest rozdzielenie dwóch zadań wykonywanych przez Git:
- przechowywanie historii wersji, dzięki czemu możesz cofnąć błędną edycję i zobaczyć, co się zmieniło oraz kiedy
- przenoszenie gotowych plików w miejsce, z którego są serwowane
Ani jedna z tych czynności nie wymaga koniecznie użycia Git. rsync, klient FTP lub formularz do przesyłania plików przez przeglądarkę doskonale nadają się do publikowania strony, a zwykłe kopie zapasowe mogą pełnić rolę historii zmian w małym projekcie osobistym. Git jest popularny, ponieważ umożliwia wykonywanie obu tych zadań jednocześnie, nie kosztuje nic i integruje się z bezpłatnym hostingiem, co czyni go najprostszym rozwiązaniem, a nie obowiązkiem.
Różnica między idealnym schematem a rzeczywistym budowaniem
Na papierze architektura generatora blogów jest niemal nudnie uporządkowana:
- artykuły to pliki Markdown w folderze
posts/ - szablon w folderze
layout/renderuje je - ten szablon łączy fragmenty HTML z foldera
partials/, takie jakheader.htmlifooter.html
config.yml (lub równoważny) znajdujący się w korzeniu projektu zawiera parametry ogólne dla całego strony, takie jak nazwa czy kolory"2024-03-14-my-post-title.md"Część, której nie pokazuje diagram, to mechanizmy realizacji. Przekształcenie tych folderów w gotową stronę, na przykład w katalogu _site/, wymaga środowiska wykonawczego języka programowania do uruchomienia generatora, a każdy ogniwko w tym łańcuchu może stać się przyczyną awarii.
Narzędzia typu mainstream starają się ukryć to za jednym poleceniem, takim jak hugo build lub npx @11ty/eleventy --serve. Opcja --serve w poleceniu Eleventy uruchamia lokalny serwer rozwojowy i przeprowadza ponowną kompilację za każdym razem, gdy zapiszesz plik źródłowy, zamiast skompilować raz i zakończyć pracę. To szybkie zamknięcie pętli sprzężenia zwrotnego sprawia, że edycja strony statycznej wydaje się niemal tak natychmiastowa jak edycja strony online.
Płatformy deploymentu przenoszą tę samą koncepcję do chmury. Netlify lub samodzielnie hostowalny Coolify uruchamiają proces budowania na zdalnym komputerze, wykrywają użyty generator, wykonują odpowiednią komendę i publikują folder z wynikami pod adresem takim jak yoursitename.netlify.app. Koncepcyjnie jest to takie samo, jak przesyłanie ręcznie napisanego HTML do Neocities i otrzymywanie adresu yoursitename.neocities.org, z tą różnicą, że proces budowania odbywa się na ich serwerze. Podobne rozwiązania oferują surge.sh, GitHub Pages, Vercel oraz produkt Pages od Cloudflare; wybór zależy od tego, jak ważna jest dla Ciebie wygoda w porównaniu z niezależnością od dużych platform. Jeśli chcesz zobaczyć kompletny proces deploymentu od początku do końca, nasze przewodnictwo na temat przesyłania małej strony internetowej do Cloudflare przedstawia konkretny przykład.
Dlaczego pojedyncza przecinka na końcu może wszystko zepsuć
Każda z tych wygód opiera się na założeniach: pliki są poprawne, środowisko językowe zainstalowane prawidłowo, a użytkownik swobodnie radzi sobie w terminalu. Programiści często przeceniają powszechność tej ostatniej umiejętności, co doskonale pokazuje ten komiks XKCD.
Proces budowania jest również kruchy. Jeden mały błąd składniowy w ważnym pliku, nawet taki prosty jak dodatkowa przecinka, może całkowicie zatrzymać instalację lub proces budowania. Co gorsza, komunikat o błędzie pochodzi zazwyczaj od samego środowiska lub parsera, a nie od generatora, dlatego jest sformułowany w kategoriach języka programowania, a nie strony internetowej. Realistyczny przykład: plik danych JSON z przecinką na końcu po ostatniej właściwości powoduje niepowodzenie procesu budowania w Netlify, przy czym ślad wywołań parsera w ogóle nie wspomina o rzeczywistym pliku, a jest sformułowany w sposób zrozumiały dla początkujących.
W obliczu takiego wyniku wiele osób rozsądnie decyduje się pisać HTML ręcznie, przenieść się na CMS hostowany online lub w ogóle zrezygnować z posiadania strony. To ostatnie rozwiązanie stanowi prawdziwą stratę. Kilka nawyków zmniejsza szanse na jego wystąpienie:
- uruchamiać proces budowania lokalnie przy użyciu serwera rozwojowego przed wysłaniem zmian, aby błędy pojawiły się najpierw na twoim ekranie
- mieniać jedną rzecz naraz, dzięki czemu najnowsza edycja staje się oczywistym podejrzanym, gdy coś się psuje
- czytać komunikat o błędzie od dołu do góry i szukać nazwy pliku oraz numeru wiersza, które zazwyczaj są prawdziwym tropem
- walidować pliki JSON i YAML za pomocą rozszerzenia edytora lub narzędzia lintera, ponieważ te formaty powodują dużą liczbę błędów u początkujących
- często zapisywać aktualny stan pracy, aby zawsze móc wrócić do ostatniej poprawnie skompilowanej wersji
Nauka poprzez modyfikację szablonu początkowego
Skutecznym sposobem na naukę pracy z generatorami jest użycie gotowego startera lub tematu, rozpoczęcie jego tworzenia, a następnie stopniowe modyfikowanie go, aż zrozumiesz każdy plik. W końcu będziesz wiedział na tyle, by stworzyć coś własnego od zera. Dobrzy starterzy do tego celu charakteryzują się kilkoma cechami: jasną dokumentacją, niewielką liczbą plików oraz jednym oczywistym miejscem na treści i ustawienia. Typowe przykłady wyglądają następująco:
- starter Hugo, w którym wpisy znajdują się w katalogu
/post, a personalizacja strony odbywa się w plikuhugo.toml, ewentualnie z funkcjami IndieWeb takimi jak microformats2 oraz gotowym h-card - starter Eleventy, w którym wpisy są przechowywane w katalogu
/posts, a informacje o stronie znajdują się w pliku danych typusite.js - starter Jekyll, w którym wpisy są umieszczane w katalogu
/_posts, a ustawienia znajdują się w pliku_config.yml
Celowo proste wersje początkowe stanowią zaletę przy nauce. Gdy stylizacja jest minimalna, struktura jest łatwa do zrozumienia, a cała praca nad projektem pozostaje do wykonania przez Ciebie.
Kleine generatory prawie bez ruchomych elementów
Hugo, Eleventy i Jekyll to popularne wybory, ale istnieje cała rodzina bardzo małych generatorów przeznaczonych dla osób, które chcą zrozumieć całe narzędzie w ciągu popołudnia.
- barf, skrót od „blogs are really fun”, to skrypt wierszowy o długości około 170 linii stworzony przez btxx, wywodzący się z projektu blog.sh Karla Bartela. Nie zawiera on żadnych elementów wstępnych ani szablonów. Tworzysz pliki w formacie Markdown, uruchamiasz
make build, a następnie przesyłasz powstałą folderówkębuild/za pomocą rsync. Feedy RSS są generowane automatycznie, skrypt działa natywnie na OpenBSD, macOS i Linux, a jego plik stylów ma zaledwie cztery linie. README oraz żywa demonstracja pokazują, jak wygląda ostateczny rezultat.
bb.sh, składający się z około 1000 linii i nie wymagający żadnych dodatkowych zależności poza standardowymi narzędziami Unixa takimi jak date, grep, sed oraz head. Pierwszą wersję napisał Carlos Fenollosa w 2011 roku, wyjaśniając wówczas swój podejście na blogu; w momencie pisania tego tekstu projekt nadal był utrzymywany. Gdy bb.sh znajdzie się w publicznym katalogu twojego serwera, polecenie ./bb.sh post utworzy nowy wpis. Projektowanie wstępne, tagi, format Markdown oraz RSS działają bez konieczności żadnej instalacji. Community fork o nazwie bashblog-ng dodaje kolejne funkcje.Kilka innych informacji, które warto znać:
- ssg to skrypt shell zgodny z POSIX, stworzony przez Romana Zolotareva, który inspirował kilka narzędzi z tej listy; pyssg to jego wersja napisana w Pythonie.
- sw, napisany w języku C, to celowo minimalistyczne frameworki internetowe, a jego odmiana simple-static jeszcze bardziej go upraszcza – według opisu w pliku README jest to najprostszy generator stron statycznych, jaki mógł sobie wyobrazić jego twórca.
- makesite.py to odpowiednik w Pythonie narzędzi barf i bashblog, składający się z mniej niż 130 linii kodu; został stworzony przez Sunainę Pai na zasadzie, że sam kod stanowi dokumentację. Nie ma warstwy konfiguracji – wystarczy przeczytać skrypt i edytować go bezpośrednio.
Żadne z tych narzędzi nie dorównuje funkcjonalnością Hugo czy Eleventy, i to właśnie jest ich cechą charakterystyczną. To, co tracą pod względem pluginów i formatów szablonów, rekompensują przejrzystością: gdy coś się zepsuje, cały program mieści się na ekranie.
Jeśli jesteś otwarty na całkowite opuszczenie świata internetu, publikowanie w protokole Gemini to kolejna opcja. Strony Gemini wykorzystują prosty format tekstowy dostarczany w niezmienionej formie, więc często w ogóle nie ma potrzeby niczego generować.
Główne wnioski
- Najpierw naucz się ręcznie pisać strony; generator automatyzuje powtarzalne czynności, które i tak już znasz.
- Największe zamieszanie związane z SSG wynika z błędnego użycia słownictwa. Gdy źródło, wynik, proces budowania, układ, fragmenty oraz informacje wstępne będą jasne, dokumentacja każdego narzędzia będzie wyglądać podobnie.
- Układy, fragmenty oraz pliki z danymi globalnymi istnieją po to, aby zmiana wprowadzona raz pojawiła się we wszystkich miejscach podczas kolejnego procesu budowania.
- Git zapewnia historię zmian oraz sposób publikacji, ale rsync, FTP lub przesyłanie plików przez przeglądarkę to również dopuszczalne alternatywy dla strony osobistej.
Literatura pokrewna
- Mapowanie słownictwa autoryzacji: klucze API, sesje, JWT, OAuth2, OIDC, SSO — Dowiedz się, jak klucze API, sesje, JWT, OAuth2, OpenID Connect i SSO współpracują ze sobą, rozpatrując każdy z nich w kontekście jednego pytania: kto wywołuje funkcję i co może zrobić.
- Angular CLI ponad ng serve: Generatory, cele, cache i statystyki budowy — Poznaj opcje Angular CLI, które eliminują rutynową pracę: flagi generatorów, wbudowana pomoc, polecenia specyficzne dla projektu, cele ng run, czyszczenie cache oraz statystyki budowy.