Перейти к тексту
ProHomeLab
EN

Automation

Своя тема для Astro вместо Hugo и Blowfish - зачем я перевел ProHomeLab на собственный движок

Stilicho201119 мин чтения7 просмотров

Эта статья на других языках: EN

Содержание

Это пятая часть цикла про то, как устроен сайт ProHomeLab. В первой статье я настроил публикацию из Obsidian через Forgejo, во второй переехал с хостинга провайдера на GitHub Pages, в третьей попробовал свести все в один репозиторий с GitHub Actions, а в четвертой от этой идеи отказался и вернулся на два репозитория Forgejo.

Все это время менялась только доставка. Сам сайт оставался на Hugo с темой Blowfish, про установку которой у меня есть отдельная инструкция. Теперь поменялся и он. С 15 ноября 2026 года prohomelab.com работает на моей собственной теме для Astro.

Информация

Адреса статей остались прежними, контент в Obsidian я не трогал, публикация по-прежнему запускается обычным пушем. То есть в этой части ничего не меняется. Статьи пишу в Obsidian, плагин Obsidian Git отправляет изменения в репозиторий со статьями на моем Forgejo, после этого запускается сборка в соседнем репозитории в том же Forgejo, а итоговый результат уходит на Github Pages, которые выступают в качестве хостинга сайта.

Ниже - зачем я это сделал, что не должно было сломаться, как проходила работа и что получилось. Подробно, со всеми затыками, с которыми я столкнулся.

Почему не остался на Blowfish

Честный ответ может показаться детским. Я просто не могу сидеть на месте. Если что-то работает, мне все равно хочется это улучшить, даже если в силу возраста на практике знаю, что «работает - не трогай». Но за этим «хочется» есть вполне конкретные причины.

Чужая тема остается чужой

Blowfish - хорошая тема. Нет, очень хорошая тема. Она быстрая, в ней огромный набор шорткодов, визуальных эффектов и у нее нормальная документация. Но это чужой продукт со своими решениями. Пока сайт похож на демо темы, все прекрасно. Как только хочется сделать по-своему, начинается борьба с теми или иными трудностями.

Перед переездом я провел аудит своего репозитория на Hugo. Своего кода там набралось около 1200 строк, и заметная часть - это копии файлов темы с моими правками:

Файл Что там было
layouts/_default/single.html копия шаблона статьи Blowfish 3.8.0 плюс темная полоса с плеером YouTube над текстом
layouts/partials/schema.html копия разметки для поисковиков плюс тип VideoObject для роликов
assets/js/code.js копия скрипта темы ради другой кнопки копирования кода
assets/css/custom.css 331 строка своих стилей поверх темы

Каждая такая копия - мина замедленного действия. Тема обновилась до 3.9.0, а у меня в single.html осталась логика от 3.8.0. Что поменялось в оригинале и что теперь не так у меня, приходится выяснять каждый раз индивидуально. Шаблоны Hugo вдобавок не самая приятная вещь для правки - логика на Go templates с точками, with и range читается тяжело. А если ты еще и не веб-дизайнер, верстальщик и вообще «магл», то задача сделать все красиво становится из области фантастики.

Все сайты на Hugo неуловимо похожи

Второе, что меня раздражало, - узнаваемость или повторяемость. Откройте десяток блогов на Blowfish, PaperMod или Congo, и вы почти сразу поймете, на чем они сделаны. Шапка, карточки, отступы, типографика - все из одной коробки. Готовые темы еще и задают рамки, за которые без копирования шаблонов не выйти.

А сейчас к этому добавилась вторая волна одинаковости - дизайн от ИИ. Фиолетово-синие градиенты, стеклянные карточки, свечение, эмодзи в заголовках, одинаковые скругленные плитки. В дополнение, когда глаз уже наметан, по цвету и шрифтам становится понятно, какая модель использовалась. От этого уже тошнит, и делать сайт в таком стиле я точно не хотел. К этому вопросу я еще вернусь по тексту статьи.

Опыт с темами для Astro

Astro я пробовал и раньше. Между первой и второй версией сайта на Blowfish был период на Astro с темой Twilight, а до этого я смотрел Fuwari. Именно с тех времен у части статей остались старые адреса, которые потом пришлось прописывать в aliases.

Главная проблема тех тем не в Astro, а в том, как они устроены. Это стартовые шаблоны. Вы клонируете репозиторий темы, и он становится вашим сайтом. Код темы, ваши настройки и ваш контент живут в одной куче. Вышло обновление темы - его нужно вручную интегрировать в свой форк, и обновление с радостью, причмокивая еще, перетирает ваши настройки. Плюс обе темы сделаны в первую очередь для китайской аудитории, и это чувствуется во всем, от шрифтов до набора интеграций.

Поэтому главное требование к своей теме появилось сразу. Тема должна быть пакетом, как любая другая зависимость, а сайт - пользователем этого пакета. Сайт настраивает тему через конфиг и при необходимости подменяет отдельные компоненты, но код темы не правит никогда. Обновление темы - это простая команда npm update, а не слияние веток.

Хочется большего, чем блог

На Hugo все, что сложнее статьи, делается через ...одно место... непросто. А у меня в планах интерактивные вещи прямо на сайте, например, хочу интегрировать калькулятор 10-дюймовой стойки, и создать отдельный раздел новостей про homelab и self-hosting. В Astro для этого есть острова - интерактивные компоненты, которые загружают свой JavaScript только там, где нужны, а остальная страница остается обычным HTML.

Тема не только для меня

И последнее. Я хочу, чтобы тема была отдельным продуктом, который можно выложить на GitHub и в npm, и взять за основу. Многие пишут в Obsidian, ведут блог на нескольких языках и мучаются с теми же проблемами, что и я. Поэтому тема с самого начала делалась не «под ProHomeLab», а для любого автора. Сайт ProHomeLab - просто ее первый пользователь, если сайт можно назвать пользователем конечно. Если какой-то функции нет в моих статьях, но она нужна другим, она все равно делается целиком и проверяется на демо-сайте.

Что такое Astro

Astro - открытый веб-фреймворк для сайтов, где главное - это содержимое: блоги, документация, сайты проектов. Как и Hugo, он собирает сайт заранее, в момент сборки, и на выходе получаются обычные HTML-файлы, которые можно положить на любой хостинг. Разница в том, как устроен сам сайт. Hugo - один исполняемый файл на Go с шаблонами на Go templates, а Astro работает на Node.js, ставится через npm, и сайт в нем собирается из компонентов. Компонент .astro похож на HTML-файл со вставками JavaScript, и этот JavaScript выполняется только при сборке, в браузер он не попадает. Код в браузер уходит, только когда об этом прямо попросили, например у интерактивного блока с директивой client:load или client:visible. Такие блоки называют островами. Остров можно написать хоть на самом Astro, хоть на React, Vue или Svelte, а вся остальная страница остается статичным HTML без лишних скриптов. Сервер при этом не обязателен. Astro умеет и отрисовку страниц на сервере по запросу, но мой сайт собирается полностью статически и отдается с GitHub Pages, как и раньше. Если любопытно, кто еще на нем работает, загляните в витрину сайтов на Astro, там хватает и крупных компаний.

Почему Astro

Можно было написать свою тему и для Hugo. Но я подумал, что если уходить от чужого кода, то уходить и от неудобных шаблонов. Что мне дает Astro:

  • Компоненты вместо шаблонов. Разметка, данные и стили страницы лежат в одном понятном файле .astro, а не размазаны по partials.
  • Коллекции контента со схемой. Фронтматтер статей проверяется при сборке. Опечатка в дате или ссылка на несуществующую обложку останавливает сборку с понятной ошибкой, а не превращается в молча пропавшую картинку на сайте. А о пропавшей картинке я могу и не узнать, пока мне не напишут читатели, а они не напишут.
  • API интеграций. Тему можно оформить как интеграцию - пакет, который сам добавляет в сайт страницы, обработку Markdown, типы и скрипты. Это ровно то, что нужно для схемы «тема как пакет».
  • Статическая сборка. Результат - обычные файлы, которые отдаются с GitHub Pages так же, как раньше отдавался результат Hugo. Никакого сервера.

Работа шла на Astro 7.4. Markdown обрабатывается через Unified (remark и rehype), потому что под него есть нужные мне плагины, например для директив и wiki-ссылок Obsidian.

Что нельзя было ломать

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

Адреса. Это главное. На статьи ссылаются YouTube, Telegram, другие сайты и поисковики. Каждая история со сменой движка у меня раньше заканчивалась охапкой ошибок 404 в Google Search Console. В этот раз ни один публичный адрес не должен был пропасть.

Контент из Obsidian без правок. Статьи живут в Obsidian и синхронизируются в Forgejo, как я описывал в статье про свой процесс от заметки до статьи. Фронтматтер в стиле Blowfish, шорткоды {{< mermaid >}} и {{< alert >}}, вставки ![[...]], относительные картинки - все это должно было работать как есть, без массовых правок, а по возможности вообще без правок.

Два языка по-настоящему. Перевод статьи - отдельный файл index.en.md, связи между версиями для поисковиков (hreflang), переключатель языка только туда, где перевод есть.

Все, что делал Blowfish. Хлебные крошки, оглавление с подсветкой текущего раздела, прогресс чтения, серии, похожие статьи, теги и категории, поиск, RSS, sitemap, режим чтения, темная тема.

Публикация прежним путем. Пуш в репозиторий статей, сборка в Forgejo Actions, выкладка на GitHub Pages.

Как шла работа

Сначала про главное, что многие спросят, а еще больше подумают.

Я не дизайнер и не верстальщик

Я не умею верстать на уровне, которого хотел от сайта, и не умею рисовать интерфейсы. Поэтому код темы писали ИИ-ассистенты - Claude Code, и, как это ни странно, Codex. Решения при этом принимал я, и результат проверял тоже я.

Сразу оговорюсь, чтобы не было иллюзий. Это не было «эй, сделай мне сайт». У меня уже был готовый сайт со своим дизайном на вылизывание которого я потратил уйму времени, со своими блоками и своей разметкой, и задача была перенести все это на новый фреймворк, ничего не потеряв. У меня было четкое понимание, как все работает на Hugo, четкое понимание чего я хочу, а главное, чего я не хочу ни при каких условиях. Каждый шаг шел с длинным списком требований, потом с проверкой и правками, потом с новыми правками. Только перенос фактически готовой темы занял у меня с ИИ больше 24 часов непрерывной работы (я засекал), и это без учета моих проверок и решений между шагами.

Скажу прямо, без контроля ИИ делает ровно тот дизайн, который лично у меня вызывает чувство отторжения. Попросите «современный сайт для блога», и получите градиенты, свечение и стеклянные плашки. Например, Claude любит свой родной терракот. Кнопки на Blowfish у меня были покрашены в медовый янтарь, мне кажется, это красиво, но кто эту разницу поймет? Поэтому я максимально бил их по рукам.

  • Шрифты и цвета только после обсуждения. Никакой самодеятельности. Цвета взяты из брендбука ProHomeLab в «тихом» варианте (тихий - это моя внутренняя терминология) - графит, нейтральные ссылки, мятный цвет только в мелочах, градиент только тонкой линией, янтарь только точкой в логотипе. Шрифт заголовков и текста - Geologica, для кода JetBrains Mono. Unbounded, который раньше стоял на сайте и в логотипе, я выбросил совсем. Он сейчас везде и сам по себе выглядит как ИИ, даже если ИИ тут ни при чем.
  • Никаких украшений ради украшений. Без частиц, маскотов, анимаций на каждом блоке и «hero» с переливающимся фоном
  • Проверка по правилам, а не на глазок. Длина строки, размер кнопок, контраст, порядок заголовков проверялись по правилам доступности. Например, правило говорит, что в строке должно быть 65-75 знаков, а для плотности я хотел текст шире. Сошлись с ИИ на компромиссе - 79 знаков в среднем. Это осознанное отступление, а не случайность. Ну или случайности неслучайны.
  • Сравнение со старым сайтом. Ширина текста, плотность страницы, поведение на телефоне сравнивались с Blowfish по цифрам на разных ширинах экрана. Это у меня много времени заняло, с учетом, что у моего телефона узкий и вытянутый экран.

Ассистенты при этом ошибались, и ошибались неочевидно. Пара примеров, которые нашлись только благодаря проверкам. На Windows файловая система не различает регистр букв, и редирект со старого адреса /posts/Name/ молча перезаписывал саму статью /posts/name/. Так пропали девять русских статей, и заметил я это не сразу - адрес-то отвечал, только вместо статьи там стоял редирект. После этого скрипт сверки научился отличать настоящую статью от страницы-редиректа. Другой случай - подсказка выбора языка. Если читатель выбрал английский, а потом нажимал «RU» в блоке «Другие языки» под заголовком, его возвращало обратно на английский. Нашлось при проверке в браузере, до публикации.

Отсюда мой главный вывод про работу с ИИ. Он ускоряет все, кроме проверки. Проверять приходится больше, а не меньше. И по иронии получается, что времени ты тратишь больше, чем если бы все делал сам (с учетом, конечно, что ты это можешь все сделать сам).

Порядок работы

Работа шла по фазам, и самое рискованное проверялось первым:

  1. Каркас - пакет темы, одна страница статьи, демо-сайт, первая страница документации.
  2. Паритет с текущим сайтом - все, что нужно ProHomeLab, плюс сверка адресов. Без этого переключение не начиналось.
  3. Переключение - только когда сверка дает ноль расхождений и после моего просмотра.
  4. Новое - новости, интерактивные инструменты, картинки для превью ссылок.
  5. Публичный релиз - GitHub, npm, версии.

Каждое решение, у которого были варианты, записывалось отдельной заметкой с контекстом, вариантами и выводом. Таких записей сейчас тринадцать. Каждый шаг - отдельная запись в журнале в Obsidian. Про объем текста я промолчу. Ну, я думаю, объем работы приблизительно понятен. Это я про кликбейтные ролики о том, как ИИ кому-то сделал сайт за пять минут (правда забыл объяснить как все работает). Документация темы писалась вместе с кодом, вернее параллельно, функция без страницы документации и примера в демо считалась невыполненной. Эту задачу я поставил сам себе с первого дня, потому что тема планируется публичной, а разбираться потом в недокументированном коде не хочется никому, включая меня самого.

По календарю первые две фазы с переключением уложились в два календарных дня. Но за этими двумя днями стоят больше суток непрерывной работы ИИ и десятки кругов «требования, результат, проверка, правки» с моей стороны. Хотел бы пошутить про мясного прокси, но задачу-то тоже я поставил. Быстро здесь только то, что ассистент не устает, «устают» лимиты. Решать, проверять и возвращать на доработку приходилось мне, и это, ой, как утомительно.

Сверка адресов

Это самая полезная часть всего переезда, и на ней стоит остановиться отдельно.

Я не стал верить sitemap. В нем нет страниц тегов, редиректов со старых адресов и лент RSS. Вместо этого я собрал Hugo-сайт целиком во временную папку на Windows и составил из результата полный список адресов с их типами. Получилось 1338 адресов. Сам удивился.

Дальше получилось так. 702 из них - это побочные продукты Hugo, на которые никто не ссылается:

  • автоматический редирект /page/1/ для каждого списка и каждого тега - 348 штук
  • отдельная лента RSS для каждого раздела и тега - 352 штуки
  • поисковый индекс Blowfish index.json - 2

Эти адреса я решил не повторять. Публичных адресов, которые действительно используются, осталось 636. Это статьи, разделы, страницы тегов, категорий и серий, главные ленты, sitemap, robots.txt и 76 старых адресов из aliases, которые должны вести на новые.

Скрипт сверки проверяет, что новая сборка отдает каждый из 636 адресов, причем статья должна быть статьей, а не редиректом. Если хоть чего-то нет, скрипт завершается с ошибкой. Этот же скрипт теперь стоит в сборке на Forgejo, и сайт не опубликуется, если какой-то адрес пропал, а я сразу понимаю, где накосячил. Ну или не я. Число расхождений было главным показателем прогресса этой фазы, и переключение началось только при нуле расхождений.

На страховку остается отчет 404 в Search Console. Если какой-то из выброшенных адресов кому-то все-таки нужен, он там появится, я это увижу и добавлю его в aliases.

Что в итоге получилось

Тема умеет все, что умел Blowfish на моем сайте, и немного больше. Перечислю то, что видно читателю.

Статья. Обложка или ролик YouTube над текстом, оглавление с подсветкой текущего раздела, прогресс чтения, серии, похожие статьи, предыдущая и следующая, кнопки «поделиться», режим чтения, блок автора. На широком экране таблицы и скриншоты выходят за колонку текста в свободное поле, а блоки кода стоят ровно по колонке, а сам текст остается удобной ширины.

Списки и таксономии. «Все статьи» по годам, разделы по папкам, закрепленные статьи, теги, категории, серии, страницы авторов. Адреса тегов строятся по тем же правилам, что в Hugo, поэтому они совпали без ручной работы.

Разметка. Шорткоды Blowfish работают как есть (учтите, что мы говорим о другом фреймворке), у каждого есть и вторая форма записи для нового контента. Callout в стиле Obsidian и GitHub, формулы, диаграммы Mermaid, вставки Obsidian, карточки репозиториев, галереи, вкладки, шаги.

Поиск. Pagefind, отдельный индекс для каждого языка, без сервера. Открывается кнопкой в шапке или клавишей /.

Языки. Если браузер читателя не на русском (украинский, белорусский и казахский я тоже считаю русскими, их читатели обычно читают по-русски), сверху появляется полоса «This page is available in English» с кнопками. Автоматически никого не перекидывает, это рекомендации Google. Выбор запоминается. Плашка про аналитику тоже говорит на языке читателя.

Страница 404 на обоих языках, с подсказками похожих статей по словам из неправильного адреса.

Просмотры. Раньше счетчик просмотров и лайки работали через Firebase. От Firebase и лайков я отказался. Это блажь. Просто когда я только начинал, я почему-то посчитал, что это полезная «красивость». Вырос, понял, что не нужно. Просмотры теперь берутся из моего локального Umami при каждой сборке и вписываются прямо в страницы, браузер читателя за ними никуда не ходит. Минус в том, что Umami у меня стоит с октября 2026 года, поэтому цифры меньше прежних.

Заметка

На всякий случай для особо любопытных. Адрес самого Umami на сайт не попадает. Счетчик в браузере читателя загружается с stats.prohomelab.com - это Cloudflare Worker, о нем ниже. Внутренний адрес, по которому сборка забирает просмотры, тоже живет только в настройках сборки.

Аналитика по согласию. Яндекс Метрика, Google Analytics и Umami не загружаются, пока читатель не нажмет «Разрешить». Обе кнопки, «Разрешить» и «Отказаться», выглядят одинаково, чтобы не подталкивать к согласию. Я «таким» не занимаюсь.

Сначала телефон. Верстка пишется для узкого экрана и расширяется для широкого. На 360 px ни одна страница не прокручивается вбок, кнопки не меньше 44 px. Каждая функция проверялась на телефоне и на десктопе, прежде чем считалась сделанной. Хотя, кому я вру? Я до сих пор вылавливаю мелкие баги.

Как теперь публикуются статьи

Схема осталась той же, что в четвертой статье, поменялись участники.

  1. Я пишу статью в Obsidian, Obsidian Git отправляет ее в репозиторий статей на Forgejo
  2. Маленький workflow в репозитории статей вызывает через API сборку в репозитории сайта
  3. Сборка на раннере Forgejo забирает сайт, тему и статьи, ставит зависимости через npm ci, собирает сайт, берет просмотры из Umami и сверяет все 636 адресов
  4. Если все в порядке, папка с готовым сайтом уходит в ветку gh-pages нового репозитория на GitHub, и GitHub Pages отдает ее на домене prohomelab.com

Сборка с нуля занимает чуть больше двух минут.

По дороге было несколько интересных и поучительных для меня моментов.

Umami за Authentik. Публичный адрес моего Umami закрыт Authentik, открыты только скрипт счетчика и прием статистики - без них счетчик у читателей просто не работал бы. Сборка, которая пыталась войти в API Umami, получала вместо ответа страницу входа Authentik. Открывать API наружу я не собирался. Сборка ходит в Umami по внутреннему адресу, мимо прокси, а адрес лежит в переменной Forgejo. Для этого в Umami заведен отдельный пользователь только с правом просмотра.

Межсетевой экран. Следующая попытка закончилась ошибкой fetch failed. Раннер и Umami живут в разных подсетях, и между ними стоят правила. Ping проходил, а соединения на порт отбрасывались. Помогло одно правило - раннеру разрешен доступ к одному порту Umami, больше ничего.

Свой адрес для счетчика. Скрипт счетчика браузер читателя грузит напрямую, поэтому его адрес (счетчика) виден в коде любой страницы. Раньше там был домен моего Umami, а светить его я не хотел. Теперь между сайтом и Umami стоит маленький Cloudflare Worker на stats.prohomelab.com. Он пропускает к Umami ровно пять адресов, которые нужны браузеру - два скрипта, прием просмотров, прием записей сессий и их настройки, - а на все остальное, включая вход в панель, отвечает 404. Адрес читателя Worker передает Umami отдельным заголовком, но только для двух вещей - определить по своей базе GeoLite страну и город, и отличить один визит от другого. Сам IP Umami не хранит, в его базе для этого даже нет поля, и мне его не показывает, в статистике я вижу только страну, город, браузер и устройство. Без этого заголовка все посетители оказались бы там же, где работает Worker. Бесплатного тарифа Cloudflare для этого хватает с запасом. Проверял заходом с телефона - визит появился в Umami сразу, и страна определилась верно, по адресу, с которого телефон выходил в интернет.

Первый запуск без публикации. Шаг выкладки на GitHub включается только тогда, когда задан репозиторий для публикации. Первые запуски на настоящем раннере собирали и проверяли сайт, не трогая живой. Очень рекомендую так делать при любом переезде.

Переключение домена

Сам переезд занял несколько минут. Важен был порядок.

Сначала я перенаправил сборку. Старая сборка Hugo при каждой новой статье выкладывала в старый репозиторий файл CNAME с моим доменом. Если бы она сработала после переноса, GitHub мог вернуть домен старому репозиторию. Поэтому сначала workflow в репозитории статей начал вызывать новую сборку, и только потом я перенес домен.

Перенос в GitHub Pages - это убрать домен в настройках старого репозитория и вписать его в новом. DNS менять не пришлось, оба репозитория принадлежат одному аккаунту. Сертификат выпустился сразу. Статьи начали открываться с нового сайта почти мгновенно, главная еще несколько минут отдавалась из кэша CDN GitHub.

После переноса скрипт прошел по всем 636 адресам уже на живом домене. Все ответили.

Старую сборку и старый репозиторий я пока не удаляю. Откат - это перенести домен обратно и вернуть одну строку в workflow. Работа на пару минут. Через несколько недель, когда станет ясно, что откат не понадобится, старый сайт будет выключен полностью.

Что не идеально

Было бы нечестно закончить только хорошим.

  • Тема еще не опубликована. Она лежит в моем приватном Forgejo. Публичный релиз на GitHub и в npm - отдельная фаза, до нее тема не готова для чужих сайтов.
  • Документация только на английском. Русской версии пока нет, кроме главной страницы. Не хочу никого обижать, но не вижу пока смысла делать документацию на русском, даже если мне это, по понятным причинам, проще.
  • Публикация в подпапке не поддерживается. Сайт должен жить в корне домена. Адрес вида user.github.io/repo/ пока не работает.
  • Строка длиннее нормы. 79 знаков в среднем вместо рекомендуемых 65-75. Это мой выбор ради плотности. Пока с этим моментом не определился на все сто.
  • Длинные таблицы на телефоне. Таблица прокручивается в своей рамке, а строка заголовков при прокрутке вниз уходит из виду. Закрепить ее - отдельная задача.
  • Просмотры начались заново. История из Firebase не переносилась, счет идет с установки Umami. Но это скорее для меня или потенциальных рекламодателей, которые неизвестно когда еще будут.

Что дальше

Следующая фаза - то, ради чего все затевалось. Раздел новостей, интерактивные инструменты вроде калькулятора стойки, автоматические картинки для превью ссылок. После этого - публичный релиз темы с документацией.

Если вы ведете блог в Obsidian на Hugo и думаете о похожем переезде, главное, что я мог бы порекомендовать, - начинайте со списка адресов, а не с дизайна. Красивый сайт с кучей ошибок 404 в Search Console - плохой переезд. Да и в принципе красота в ущерб функционалу ничего хорошего не принесет, это я все прочувствовал на себе.