Кто я

В настоящее время эти страницы веду я, Солдатов Валерий, главный инженер ЗАО Бэст Телеком, г.Москва

(разумеется и почта, и эти страницы доступны по IPv6)

Большая просьба не забывать ссылаться на источник при перепечатке. Иначе это не перепечатка, а мелкое воровство.

Опыты с SSG

Для вёрстки и генерации этих страниц решили использовать какой-нибудь генератор статических сайтов, а динамические
вставки сделать на JS. Попробовали вот эти SSG:

Hugo
Hexo
Astro
Pelican

Пожелания были несложные:

возможность генерировать страницы (ну очевидно же)
нужна двухуровневая навигация
возможность быстро публиковать новости (посты)
новости (именно новости, а не заголовки новостей) должны быть на первой странице
вверху первой странице нужно размещать отдельный блок (суперновости, выделенные обьявления, реклама и т.п.) - то есть то, что
у дизайнеров называется hero

HEXO SSG

Эти страницы изготовлены на HEXO, далее - некоторые детали по работе с ним.

Шаблоны

(везде идёт речь про шаблонизатор nunjucks (родной брат jinja и близкий родственник mustache), его js/json синтаксис показался попроще, чем php-подобный у .ejs)

Нужно задать как минимум один шаблон (index), а лучше - три базовых шаблона: для первой страницы, для остальных страниц и для сообщений (пост). Также можно создать шаблоны для категорий, тегов, архивов и просто для отдельных страниц. Соответственно, три базовых - это

index.njk
page.njk
post.njk

В документации сказано, что существует “супершаблон” layout.njk. Если его создать, то пишут, что остальные шаблоны тогда становятся
для него вторым уровнем.

Многоуровневая навигация

“В лоб” поддерживается только одноуровневая навигация, то есть при попытке создать страницу

hexo new page about

в директории source будет создана поддиректория и появится файл source/about/index.html

а при попытке создать страницу

hexo new page about/part1

в директории source будет создана поддиректория about-part1 и появится файл source/about-part1/index.html доступный по
URL=/about-part1, а вовсе не по URL=/about/part1

Но в этом файле, в служебной части (frontmatter) можно указать

permalink: about/part1

и файл станет доступен по URL=/about/part1. Точно то же самое произойдёт при создании ещё одногo уровня вглубь: команда
hexo new page dir1/dir2/dir3 приведёт к созданию файла ./dir1-dir2-dir3/index.html

Статические файлы

Файлы из source/themes/имявашейтемы/source/ будут скопированы в корень вашего сайта. Это могут быть изображения,
файлы CSS или библиотеки/скрипты JS. Если в этой директории были поддиректории - то они будут скопированы тоже.
Практика показала, что файлы из поддиректории css копируются, а из js - нет.

Рабочие директории

Если имя директории начинается с подстрочного подчерка, то прямого пути к ней не будет, то есть:

source/data/abc.html будет доступен по URL=/data
source/_data/abc.html не будет доступен по URL=/data

Такие директории используются для хранения файлов, используемых при генерации контента, например json-файлы с данными. По
умолчанию так выглядит директория с сообщениями _posts/

Коллекции, или наборы обьектов с одинаковой структурой

В документации работа с коллекциями показана очень поверхнсстно.
Обнаружено, что нельзя использовать подстрочный подчерк или пробел в именах файлов с данными. Также не получается передать имя файла как параметр в шаблон, то есть если в файле задано

datafile: myfile.json

то конструкция вида

{% for pp in site.data.page.myfile %} работает, а

{% for pp in site.data.page.datafile %} НЕ РАБОТАЕТ

то есть попытки “прикрепить” имя файла как параметр к оператору чтения не приводят к успаху.

Использование CSS frameworks

Вот тут подстерегает засада: любой фреймворк сначала сбрасывает все установки по умолчанию. Что именно - нужно смотреть
в конкретном фреймворке, как правило они используют какой-либо сторониий файл с названием вида reset.css и включают его
в себя в самом начале.
Нет ничего страшного, но вот с markdown сразу начнуся сложности: например перестанут отображаться метки перечислений и
станут абсолютно одинаково отображаться тексты в тэгах h1, h2, …, h6.

Методы борьбы:

интеллектуальный: вскрыть итоговую CSS-таблицу, найти эти стили этих тэгов и просто удалить всё, что сбрасывает настройки. Недостаток: если вы обновите этот CSS-файл (или загрузите следующую версию), то придётся править его заново
тупой: написать маленький css-файл и подключить его последним. В файле нужно как минимум указать размеры заголовков, а также отступы и стили меток перечислений

Плагины тэгов и плагины шаблонов - разные вещи, и документация по ним тоже разная.

Плагины тэгов в основном предназначены
для использования в постах, хотя в страницах они тоже работают.

Хелперы (они же тэги шаблонов) не работают в постах и на страницах,
и предназначены для использования только в шаблонах,так как являются частью их экосистмы. Соответственно, можно пробовать использовать в шаблонах и другие “родные” тэги и хэлперы, например в Nunjucks - вот эти.

Разница между шаблонами ejs и njk

Хотя в документации Hexo сказано, что поддерживаются оба, есть существенная разница.
Пример из описания: <%- css('style.css') %> в шаблоне ejs работает, а
{% css('style.css') %} в шаблоне njk вызывает сообщение об ошибке. Утешает то, что не очень-то этот тэг нужен…

Краткие выводы

желательно брать такой SSG, который написан на знакомом языке, чтобы было проще дорабатывать (а ведь придётся…)
скорость работы SSG для генерации среднего сайта не имеет большого значения
в случае, если вас не устраивает Bootstrap или Bulma, и вы привыкли к Tailwind, то крайне желательна встроенная поддержка для него, чтобы не тратить время на динамическую минимизацию
автообновление браузера - очень удобная деталь, но у hexo отсутствует
не нужно надеяться на документацию
если у вас сайт будет состоять из сотни разделов с подразделами - то количество каталогов в source может стать запредельным

LightGallery

В <a href - большое фото
в <img - маленькое (миниатюра)

IndexedDB

https://blog.logrocket.com/using-indexeddb-complete-guide/