Генератори статичних сайтів з нуля: словниковий запас, історія та перше створення
Дізнайтеся терміни, які, за припущенням документації SSG, ви вже знаєте: як поєднуються макети, частини та фронт-матеріал, звідки взялися генератори та як обрати один без проблем.
Генератори статичних сайтів обіцяють просте рішення: пишете пости у форматі Markdown, зберігаєте заголовок та футер у одному місці, і отримуєте швидкий веб-сайт, створений зі звичайних файлів. Для багатьох початківців реальність виглядає як стіна незрозумілого жаргону, термінал, який виводить стек-трейси, та документація, яка передбачає наявність багаторічних знань. Цей посібник подолує цю прогалину з самого початку. Ви дізнаєтесь, які навички потрібні перед початком роботи, що насправді означає кожен часто зустрічаючийся термін у документації генератора, як взаємопов’язані елементи типового проекту Eleventy, звідки походять ці інструменти та які легші альтернативи існують, коли популярні варіанти здаються занадто складними.
Перш ніж обрати генератор: необхідні навички
Генератор статичних сайтів (SSG) — це шар абстракції над веб-сторінками. Якщо ви ніколи не створювали веб-сторінку вручну, цей шар абстракції приховує саме те, що потрібно зрозуміти, коли щось йде не так. Для ваших перших кількох сайтів кращим способом навчання буде самостійне написання HTML та CSS. Ви відчуєте труднощі від копіювання однакової навігації у десять файлів, і саме ці труднощі зроблять генератор корисним у майбутньому.
Майже кожен генератор припускає, що ви вже добре орієнтуєтесь у HTML та CSS, іноді також у базовому JavaScript, деяких загальних принципах програмування, таких як змінні та цикли, роботі з командною лінією та, як правило, у Git. Не потрібно спочатку опановувати все це повністю. Суть у тому, що базова когнітивна модель кожного шару перетворює загадкову помилку під час створення сайту на проблему, яку можна вирішити, а не на загадку.
Шлях навчання з безкоштовних ресурсів
Наступні ресурси ефективно працюють приблизно в такій послідовності. Створюйте невеликі тимчасові сайти по ходу роботи, замість того щоб сприймати цей список як домашнє завдання, яке потрібно виконати спочатку.
- HTML: книга HTML for People призначена для читачів без жодного досвіду програмування. Якщо ви хочете дізнатися більше про семантичні елементи та доступність, перейдіть до розділу MDN про структурування контенту.
- CSS: розділ MDN про основи стилізації охоплює такі концепції, як модель коробки та макетування. Якщо вам більше підходять практичні вправи, курс freeCodeCamp з реактивного дизайну пояснює HTML, CSS, доступність та реактивний (на практиці, придатний для мобільних пристроїв) дизайн.
- JavaScript: розділ MDN про скриптування є логічним продовженням матеріалів про HTML та CSS, а навчальна програма freeCodeCamp з JavaScript — це інтерактивна альтернатива.
Якщо ви віддаєте перевагу єдиному ресурсу замість набору матеріалів, навчальна частина MDN охоплює HTML, CSS, JavaScript та основи браузерів у єдиній навчальній програмі. Ще кілька варіантів — web.dev, The Odin Project та w3schools.
Зберігайте об’єктивність: особистий веб-сайт зазвичай є хобі-проектом. Нестандартні рішення та помилки є частиною процесу, і кожен завершений невеликий сайт додає нові навички, які можна використати у наступному проекті.
Лексика, яку, за припущенням документації static-site, ви вже знаєте
У документації до генераторів часто використовується десяток термінів, ніби всі вивчили їх з народження. У цьому розділі вони пояснюються простою мовою, а кожен з них демонструється у невеликому конкретному файлі з проекту Eleventy (11ty).
Маркування, стиль та поведінка: HTML, CSS та JavaScript
HTML (HyperText Markup Language) описує структуру та зміст документа: заголовки, абзаци, посилання, зображення, списки. Це не мова програмування. Він не може приймати рішення чи щось повторювати самостійно; він просто оголошує те, що знаходиться на сторінці. Найменша корисна сторінка містить doctype, <head> із набором символів та заголовком, а також <body> із вмістом. Зауважте, що тут немає нічого, що б керувало кольорами чи шрифтами, тому браузер використовує свої стандартні стилі.
<!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
Якщо зберегти цей файл як index.html та відкрити його в будь-якому браузері, ви отримаєте функціональну веб-сторінку без необхідності сервера. (Слово Copy, яке знаходиться після закриваючої теги, є залишком від кнопки копіювання та не є частиною маркування.)
CSS (Cascading Style Sheets) контролює те, як представляється ця структура: кольори, відступи, типографіка та те, як макет адаптується до різних розмірів екрана. Наведені нижче правила встановлюють шрифт з серифами, обмежують ширину тексту, щоб рядки залишалися читабельними, центрують колонку з автоматичними відступами та надають сторінці теплого фону та темних кольорів тексту. Заголовок має власне правило щодо кольору.
body {
font-family: Georgia, serif;
max-width: 35rem;
margin: 2rem auto;
padding: 0 1rem;
background: #fff2ce;
color: #02005d;
}
h1 {
color: rebeccapurple;
}Copy
Розміщення цих правил у елементі <style> всередині <head> попередньої сторінки змінює її вигляд, не змінюючи жодного слова HTML. Це розділення контенту та презентації є основною концепцією, яка притаманна всім генераторам статичних сайтів.
JavaScript — це мова програмування, якою працюють браузери. Вона додає функціонал: реагування на кліки, зміну вмісту, отримання даних. Водночас це найпростіший спосіб зробити просту сторінку важкою та повільною, тому хорошим стандартом для особистого сайту є використання цієї мови лише там, де вона справді є необхідною. У наведеному нижче фрагменті знаходиться елемент із id surprise, він слухає кліки на цей елемент та замінює текст першого <h1> після виконання кліку.
const button = document.querySelector("#surprise");
button.addEventListener("click", () => {
document.querySelector("h1").textContent = "JavaScript did this!";
});Copy
Щоб це спрацювало, на сторінці має бути відповідний елемент <button id="surprise">. Без нього querySelector повертає null, а виклик addEventListener призводить до помилки, що є поширеною першою проблемою.
JavaScript також використовується на стороні генератора, а не лише в браузері. Багато SSG-систем написані саме на JavaScript та використовують його для запуску процесу збірки чи обробки шаблонів. Eleventy навіть дозволяє робити весь шаблон файлом JavaScript: будь-який рядок, який повертає експортована функція, стає вмістом сторінки.
// hello.11ty.js
module.exports = function () {
return "<h1>Hello from JavaScript!</h1>";
};Copy
У цьому прикладі використовується CommonJS module.exports. Останні версії Eleventy також підтримують синтаксис ES-модулів (export default), тож перевірте, який стиль використовується у документації до вашої встановленої версії.
Що насправді означають „static“, „build“ та „output“
- Статичний описує спосіб доставки: сервер передає файл саме таким, яким він зберігається, замість того щоб створювати нову відповідь для кожного відвідувача. Статична сторінка все ще може містити JavaScript та може бути відредагована та знову розгорнута. Це нічого не говорить про те, що сторінка буде нудною чи застигне назавжди.
- Динамічний означає, що щось обчислює відповідь у момент запиту. Класична система керування контентом звертається до бази даних та складає сторінку щоразу під час візиту. Інтернет-магазин є класичним прикладом, оскільки асортимент та кошики постійно змінюються.
- Генератор статичних сайтів — це програма, яка читає вихідні матеріали (контент у форматі Markdown, шаблони, конфігурацію, зображення та інші ресурси) та створює готовий набір файлів HTML, CSS, JavaScript та зображень, які може обслуговувати будь-який статичний хостинг.
_site/, public/ або dist/. Їх зазвичай не редагують вручну, оскільки наступний build їх перезаписує.localhost:8000 та часто автоматично перестраховує його щоразу, коли ви зберігаєте файл вихідних даних.Файли конфігурації та дані сайту
- Файл конфігурації містить налаштування для всього сайту, такі як назва сайту, базова URL, меню, каталог виведення чи параметри подачі контенту. Назви та формати відрізняються залежно від інструменту:
config.yml,hugo.toml,eleventy.config.jsта інші. - YAML — це зручний для людини формат даних, який широко використовується у конфігураціях та передмовних даних. Він дозволяє представляти рядки, числа, списки та пари „ключ-значення“. Відступи мають значення, тому неправильно розміщений пробіл може зруйнувати процес створення сайту.
- Пара ключ-значення — це налаштування, яке складається з імені та значення, наприклад
title: My post. У YAML група таких пар називається мапуванням. - Параметр чи опція — це налаштування, яке ви передаєте команді чи записуєте у файл. Прапорець
--serve, з яким ви зустрінетеся пізніше, є одним із прикладів.
У Eleventy файли з папки _data стають глобальними даними, доступними для кожної шаблону. Файл src/_data/site.json містить інформацію, яку бачать відвідувачі: назву сайту, короткий опис, автора, публічну URL-адресу та мову.
{
"name": "My Cool Blog",
"description": "Where I write about whatever interests me.",
"author": "Your Name",
"url": "https://example.com",
"language": "en"
}
Кожен ключ перетворюється на змінну шаблону. Лейаут, який містить {{ site.name }}, відображає значення „My Cool Blog“, тож зміна назви сайту означає редагування лише одного рядка тут, замість пошуку на кожній сторінці. Jekyll зберігає подібну інформацію у файлі config.yml, а Hugo — у файлі hugo.toml; ідея однакова, лише змінюється файл. Пам’ятайте, що JSON є суворим форматом: крапка після останнього елемента є синтаксичною помилкою, і цей момент стане важливим пізніше в цьому посібнику.
Лейаути, частини та шаблонування
- Шаблон — це повторно використовуваний файл, який визначає структуру сторінки та містить місця для заміни частин, які можуть змінюватися.
- Макет — це шаблон для всієї сторінки: оголошення мови, тег
<head>, заголовок, основна область вмісту та футер. - Частковий елемент — це невеликий повторно використовуваний фрагмент, такий як панель навігації, футер чи блок метаданих посту. Включення — це інструкція, яка додає один фрагмент до іншого файлу.
- Мова шаблонів — це синтаксис для виведення змінних, обробки даних у циклах та прийняття рішень усередині шаблонів. Поширеними прикладами є Liquid, Nunjucks та Go templates.
- — це правило типу «так» чи «ні» у шаблоні, наприклад «відображати головне зображення лише тоді, коли пост його визначає».
Основна структура нижче, _includes/layouts/base.njk, написана мовою Nunjucks. Заголовок поєднує власний заголовок сторінки з глобальною назвою сайту; два теги include додають частини заголовка та футера, а оформлений корпус сторінки виводиться всередині <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>
Фільтр | safe має важливе значення. Nunjucks за замовчуванням ескейпує вихідний текст, що призводить до того, що HTML поста перетворюється на видимі теги. Позначення content як безпечного повідомляє движок про те, що цей рядок є надійним, вже оформленим HTML. Використовуйте його лише для контенту, який знаходиться під вашим контролем.
Самі частини — це просто фрагменти HTML, які можуть використовувати змінні та містити інші частини. Заголовок посилається на головну сторінку за допомогою назви сайту та завантажує навігацію; навігація — це звичайний список посилань; у футері виводиться рядок з інформацією про авторські права, взята з даних сайту.
<!-- 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>
Ось як ці елементи пов’язані між собою. Коли запис у своєму вступному тексті вказує layout: base.njk, Eleventy обробляє цей запис, потім розміщує результат там, де у лейауті знаходиться {{ content | safe }}, а кожен тег include замінюється на відповідну частину. Якщо змінити навігацію один раз, кожна сторінка сайту автоматично оновиться під час наступної обробки. Саме для усунення необхідності постійного копіювання та вставки існують SSG. Є один нюанс: рік у футері заданий жорстко, тож він не оновлюватиметься сам по собі, якщо тільки ви не заміните його на змінну.
Файли з контентом, Markdown та фронт-матеріал
- Файл з контентом — це вихідний файл для сторінки чи запису. Найпоширенішим форматом є Markdown, але багато генераторів підтримують HTML, звичайний текст та інші формати.
- Markdown — це легкий мовлення для форматування тексту, у якому пунктуація використовується для позначення структури:
#— для заголовків, зірки — для наголосу, тире — для списків. Генератор перетворює його на HTML. - Фронт-матеріал — це блок метаданих у самому верхньому розділі файлу з контентом, який зазвичай обмежений двома рядками з трьома тире. У ньому можуть бути заголовок, дата, теги, назва макету чи позначка проекту.
- Метадані — це описова інформація про контент: заголовок, автор, дата публікації, теги, опис, канонічна URL чи обраний макет.
Файл posts/my-first-post.md, наведений нижче, поєднує усе це. YAML-фронтматер визначає назву, дату, два теги, формат відображення та позначку проекту. Тіло файлу поєднує звичайний Markdown із синтаксисом шаблонів у стилі Nunjucks, який виводить назву та умовно показує речення.
---
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 читає передмовні дані перед тим, як відображати щось. Ключ layout вибирає шаблон оформлення, тег posts додає файл до колекції під назвою posts (яку може обходити сторінка архіву), а date визначає порядок сортування з урахуванням дати. Усе, що знаходиться після закриваючих дефісів, є основним контентом. Оскільки тут значення draft дорівнює false, ухилена конструкція не з’являється у результаті. Зауважте, що ключ draft не має вбудованого значення в Eleventy; виключення чернеток з фінальної версії — це те, що потрібно налаштувати самостійно.
Хостинг, бекенди та умови розгортання
- Хостинг — це сервіс або машина, яка зберігає ваші файли вихідного коду та робить їх доступними в Інтернеті. Це окрема складова, відмінна від написання сайту та керування версіями.
- Контроль версій фіксує зміни у файлах з часом, щоб ви могли переглядати історію, порівнювати версії, скасовувати зміни та співпрацювати.
- Git — це одна з програм для контролю версій. Вона працює виключно на вашому комп’ютері та не потребує онлайн-сервісів для відстеження історії змін.
- Репозиторій — це папка проекту, історію змін у якій керує Git.
- Коміт — це збережений знімок змін, зазвичай із повідомленням, що його описує.
- Віддалений репозиторій — це ще одна копія репозиторію, яка часто розміщується на Codeberg, GitHub, GitLab або вашому власному сервері.
- Push надсилає ваші локальні коміти на віддалений сервер; pull отримує коміти з віддаленого сервера та об’єднує їх із вашою локальною копією.
- Сервіси Git hosting зберігають репозиторії та часто додають функції відстеження проблем, перегляду коду та автоматичної компіляції. Вони зручні, але це не сам Git, і Git працює добре без них.
Опублікувати нову публікацію за допомогою Git з терміналу потребує чотирьох команд. Перша виконується лише один раз на проект; решта три — це щоденний цикл підготовки файлу, створення його копії та надсилання її на віддалений сервер.
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
На практиці git push працює лише після налаштування віддаленого репозиторію, наприклад за допомогою команди git remote add origin <url>, і для першого завантаження гілки зазвичай потрібна команда git push -u origin main або подібна. Після цього достатньо просто використати git push.
Звідки виникли генератори статичних сайтів
З розумінням використовуваних термінів історія розвитку стає зрозумілішою, адже кожне нове покоління інструментів додавало одну з вищезгаданих концепцій.
Розділення процесу написання коду та форматування відбувалося задовго до появи терміна „генератор статичних сайтів“. HSC, скорочення від „HTML Sucks Completely“, — це препроцесор HTML, створений Томасом Аглассінгером у 1996 році. Він вже підтримував функції включення файлів, умовні оператори та перевірку посилань, приблизно за десять років до того, як ця категорія отримала свою назву.
Протягом кінця 1990-х та 2000-х років більшість людей, які хотіли створити блог, обирали хостовані динамічні сервіси, такі як Blogger, LiveJournal чи Open Diary, або встановлювали програмне забезпечення на основі баз даних, наприклад WordPress. Movable Type – платформа на Perl, створена Беном та Меною Тротт у 2001 році – обрала інший підхід: щоразу, коли ви публікували контент через її веб-інтерфейс, система генерувала блог у вигляді звичайних статичних HTML-файлів. Користувачі ніколи не користувалися терміналом, проте читачі отримували статичні сторінки. Це надало переваги статичного формату тим, хто ніколи не буде вводити команди для створення контенту.
Nanoc з’явився у 2007 році; його створив Деніс Дефрейн після того, як системи керування контентом Ruby виявилися занадто повільними на його віртуальному сервері об’ємом 96 МБ. Він ввів можливість налаштування макетів, метаданих для кожної сторінки, підтримку Markdown та плагіни. У грудні 2008 року співзасновник GitHub Том Престон-Вернер оприлюднив Jekyll, незадоволений великогабаритними двигунами для блогів. Jekyll базується на ідеях Nanoc та додає дві ключові функції: YAML-файли з інформацією на початку кожного файлу контенту та можливість створення блогу без додаткової налаштування — тож папка з файлами Markdown автоматично стає блогом. Разом із ним було запущено GitHub Pages як безкоштовний сервіс для статичного хостингу, і саме ця комбінація більше за все сприяла поширенню SSG-систем.
Майже все, що було створено з того часу, — це переосмислення тієї ж схеми в інших мовах. Octopress, який тепер не підтримується, та Middleman продовжили розвиток серії для Ruby. Pelican базується на Python, а Hyde розроблений на основі Laravel.
У липні 2013 року Стів Франчія створив Hugo — програму на мові Go, яка постачається у вигляді єдиного скомпільованого бінарного файлу. На відміну від Jekyll не потрібно було встановлювати середовище Ruby чи узгоджувати версії gem, а швидкість компіляції, яка становила кілька секунд навіть для сайтів із тисячами сторінок, стала його особливістю.
Наприкінці 2017 року Зак Лезерман випустив Eleventy (11ty) — гнучку альтернативу Jekyll, яка працює на JavaScript та встановлюється через npm. Jekyll прив’язує користувача до формату Liquid; Eleventy підтримує велику кількість форматів шаблонів:
- форматування та контент: звичайний HTML (
.html), Markdown (.md) та MDX (.mdx)
.11ty.js, TypeScript (.ts), JSX (.jsx) та WebC (.webc).njk), Handlebars (.hbs), Mustache, EJS, Haml та Pug.scss)Деякі з цих форматів вимагають додаткового плагіна чи налаштувань, щоб працювати без додаткових зусиль, тому перевірте актуальну документацію Eleventy перед тим, як покладатися на них. Якщо ви вже знаєте певну мову програмування, каталог генераторів на Jamstack.org дозволяє вам знайти інструменти, написані саме цією мовою.
Багато генераторів у тому каталозі роками не мали нових версій, і для особистого сайту це часто є прийнятним. Статичний сайт не має коду з боку сервера чи бази даних, які б були доступні відвідувачам, що усуває найпоширенішу поверхню для атак у динамічних блогах. Якщо нова версія вашого генератора додає функції, які вам не подобаються, ви можете продовжувати використовувати стару, і вона буде продовжувати створювати той самий сайт. Однак слід пам’ятати, що «жодних оновлень» — це не те саме, що «жодних ризиків»: залежності, які використовуються під час створення, машина, на якій відбувається створення, та будь-який JavaScript від сторонніх розробників, який ви вбудовуєте, все одно потребують уваги, а необслуговуваний інструмент з часом може перестати коректно встановлюватися на новішу операційну систему чи середовище виконання мови.
Git вирішує дві проблеми, але вам не потрібен жоден з них
Посібники для початківців майже завжди радять використовувати Git. Частково це пов’язано зі звичкою розробників, але частково — з історичними причинами: Jekyll, перший широко використовуваний SSG, спочатку був проектом на GitHub. Розміщення на GitHub, Codeberg чи GitLab дає відповідь на запитання «Де знаходяться мої файли?» — «У репозиторії». Сервіси на кшталт Neocities чи Nekoweb відповідають на це інакше: ви завантажуєте файли через сам сайт.
На хостингу, заснованому на Git, такому як Codeberg Pages чи GitLab Pages, навіть зміни, внесені через веб-інтерфейс, стають комітами та пушами у фоновому режимі. Ви використовуєте Git незалежно від того, чи коли-небудь вводили команди Git чи ні.
Якщо ви самі хостите сайт, файли знаходяться на вашому власному комп’ютері, зазвичай у каталозі на кшталт /var/www/html у Linux. На спільному сервері, такому як Tildeverse, вони знаходяться у публічній папці вашого облікового запису; поширеним підходом там є створення файлів локально та використання rsync для копіювання результату на спільний комп’ютер, де вони автоматично подаються.
У таких конфігураціях корисно розділити дві основні функції Git:
- зберігання історії версій, щоб можна було скасувати неправильні зміни та побачити, що саме змінилося та коли
- надсилання готових файлів у місце, звідки вони подаються
Жодна з цих робіт не вимагає обов’язково використання Git. rsync, клієнт FTP або форма завантаження в браузері — усе це дозволяє ідеально опублікувати сайт, а звичайні резервні копії можуть слугувати історією змін у невеликому особистому проекті. Git популярний тому, що він дозволяє виконувати обидві ці функції одночасно, не коштує нічого та підтримується безкоштовними хостингами, що робить його оптимальним вибором, а не обов’язковою умовою.
Різниця між ідеальною схемою та реальною реалізацією
На папері архітектура генератора блогів виглядає майже надто простою та охайною:
- статті зберігаються у вигляді файлів Markdown у папці
posts/ - шаблон у папці
layout/відображає їх - цей шаблон складає фрагменти HTML з папки
partials/, такі якheader.htmlтаfooter.html
config.yml (або еквівалентний файл) у корені проекту містить параметри для всього сайту, такі як назва чи кольори"2024-03-14-my-post-title.md"Та частина, яку не показано на діаграмі, — це технологічний механізм. Перетворення цих папок на готовий сайт, наприклад у директорії _site/, вимагає середовища виконання програмувальної мови для запуску генератора, і кожне зв’язок у цьому ланцюзі може стати причиною збоїв.
Популярні інструменти намагаються приховати цей процес за однією командою, такою як hugo build або npx @11ty/eleventy --serve. Параметр --serve у команді Eleventy запускає локальний сервер розробки та перебудовує сайт щоразу, коли ви зберігаєте вихідний файл, замість того щоб виконати перебудову один раз та завершити роботу. Саме цей швидкий цикл зворотного зв’язку робить редагування статичного сайту майже таким же миттєвим, як і редагування живої сторінки.
Платформи для розгортання поширюють цю саму ідею на хмару. Netlify чи самостійно розгортуваний Coolify виконують процес збірки на віддаленій машині, визначають, який інструмент для генерації ви використовуєте, запускають відповідну команду та публікують папку з результатами за адресою на кшталт yoursitename.netlify.app. Концептуально це так само, як завантаження вручну написаного HTML на Neocities та отримання адреси yoursitename.neocities.org, за винятком того, що процес збірки відбувається на їхній машині. Подібні рішення пропонують surge.sh, GitHub Pages, Vercel та продукт Cloudflare — Pages; вибір залежить від того, наскільки для вас важлива зручність порівняно з незалежністю від великих платформ. Якщо ви хочете побачити повний процес розгортання від початку до кінця, наш огляд розгортання невеликого веб-сайту на Cloudflare описує один конкретний приклад.
Чому одна зайва кома може все зіпсувати
Кожен із цих зручностей ґрунтується на певних припущеннях: ваші файли правильні, мовна середовище встановлено без проблем, і ви впевнено користуєтесь терміналом. Розробники часто переоцінюють поширеність останньої навички, що добре ілюструється у цьому коміксі XKCD.
Процес компіляції також є крихким. Одна невелика помилка синтаксису у важливому файлі, навіть на кшталт зайвої коми, може повністю зупинити процес встановлення чи компіляції. Ще гірше те, що повідомлення про помилку зазвичай надходить від самого середовища чи парсера, а не від генератора, тому воно сформульоване з урахуванням особливостей програмувальної мови, а не вашого сайту. Реалістичний приклад: JSON-файл із зайвою комою після останнього поля призводить до невдачі процесу компіляції в Netlify, причому траса стеку парсера ніколи не згадує сам файл, викладена простою мовою для початківців.
Стикаючись із таким результатом, багато людей розумно вирішують писати HTML вручну, перейти на хостований CMS або зовсім відмовитися від створення сайту. Останній варіант є справжньою втратою. Кілька звичок можуть зменшити ймовірність цього:
- запускати процес створення локально за допомогою сервера розробки перед публікацією, щоб проблеми спочатку з’являлися на вашому екрані
- змінювати щось по черзі, щоб остання зміна була очевидним підозрюваним у разі збою
- читати повідомлення про помилку знизу вгору та шукати назву файлу та номер рядка, які зазвичай є справжньою підказкою
- перевіряти JSON та YAML за допомогою розширень для редактора чи інструментів лінтингу, адже саме ці формати спричиняють багато помилок у початківців під час створення проекту
- часто зберігати актуальні версії, щоб завжди можна було повернутися до останньої працездатної версії
Навчання шляхом модифікації готового проекту
Доведеним способом навчання роботі з генераторами є використання готових стартових проектів чи тем, початок роботи над ними та потім поступова зміна їх елементів до тих пір, доки ви не зрозумієте кожен файл. Зрештою ви навчитеся створювати їх самостійно з нуля. Хороші стартові проекти для цієї мети мають кілька спільних рис: чітку документацію, невелику кількість файлів та одне очевидне місце для розміщення контенту та налаштувань. Типові приклади виглядають так:
- стартовий проект Hugo, де статті знаходяться у каталозі
/post, а налаштування сайту — у файліhugo.toml; можливо, з функціями IndieWeb, такими як microformats2 та готовою карткою h-card - стартовий проект Eleventy, де статті знаходяться у каталозі
/posts, а деталі сайту — у файлі даних, наприкладsite.js - стартовий проект Jekyll, де статті знаходяться у каталозі
/_posts, а налаштування — у файлі_config.yml
Навмисно прості стартові версії є перевагою для навчання. Коли стилізація мінімальна, структура легко помітна, і вся робота з дизайном залишається на вашому розсуд.
Дуже маленькі генератори майже без рухомих частин
Hugo, Eleventy та Jekyll є популярними варіантами, але існує ціла родина дуже малих генераторів для тих, хто хоче зрозуміти всю цю інструментальну систему за один день.
- barf, скорочення від „blogs are really fun“, — це шел-скрипт довжиною близько 170 рядків, створений btxx на основі проекту Karl Bartel’s blog.sh. У нього немає вступних даних та шаблонів. Ви пишете файли у форматі Markdown, запускаєте команду
make build, а потім завантажуєте отриману папкуbuild/за допомогою rsync. RSS-канали генеруються автоматично; скрипт працює без проблем на OpenBSD, macOS та Linux, а його стилевий файл складається з чотирьох рядків. У документі README та живому демонстраційному прикладі показано, як виглядає кінцевий результат.
bb.sh, який налічує близько 1 000 рядків та не має жодних залежностей, окрім стандартних утиліт Unix, таких як date, grep, sed та head. Першу версію написав Карлос Феноллоса у 2011 році та пояснив підхід у своїй блог-статті; на момент написання цього тексту він все ще підтримувався. Як тільки bb.sh опиниться у публічному каталозі вашого сервера, команда ./bb.sh post створює нову запис. Режим редагування, теги, формат Markdown та RSS працюють без необхідності встановлення додаткових компонентів. Ком’юніті-версія під назвою bashblog-ng додає ще більше функцій.Ще кілька інструментів, про які варто знати:
- ssg — це шелл-скрипт, сумісний з POSIX, розроблений Roman Zolotarev; він став основою для кількох інструментів у цьому списку; pyssg — це переписана версія на Python.
- sw, написаний на C, — це навмисно мінімалістична веб-фреймворк, а його форк simple-static ще більше скорочує його функціонал до того, що в описі README називається найпростішим генератором статичних сайтів, який тільки може уявити його розробник.
- makesite.py — це аналог barf та bashblog для Python, що складається менше ніж з 130 рядків; його створила Сунайна Пай на принципі, що сам код є документацією. Не існує рівня конфігурації; ви читаєте скрипт та редагуєте його безпосередньо.
Жоден з цих інструментів не наближається за функціоналом до Hugo чи Eleventy, і саме в цьому суть. Те, що вони втрачають у плані плагінів та форматів шаблонів, вони компенсують прозорістю: коли щось ламається, весь програмний код поміщається на вашому екрані.
Якщо ви готові повністю вийти за межі Інтернету, публікація через протокол Gemini є ще одним варіантом. Сторінки Gemini використовують простий текстовий формат, який подається без змін, тож часто взагалі немає потреби щось генерувати.
Основні висновки
- Спочатку навчіться писати сторінки вручну; генератор автоматизує процеси, які ви вже повинні розуміти.
- Більшість плутанин із SSG пов’язана з лексикою. Як тільки стає зрозумілим значення понять «джерело», «вихідний формат», «будування», «макет», «частини контенту» та «фронт-матеріал», документація до кожного інструменту здається схожою.
- Макети, частини контенту та глобальні файли даних існують для того, щоб зміни, внесені один раз, проявлялися всюди під час наступної обробки.
- Git забезпечує історію змін та шлях публікації, але rsync, FTP чи завантаження через браузер є прийнятними альтернативами для особистого сайту.