#Hugo

В мене блог на Hugo та в цілому для мене як для інженера, та ще й з досвідом Go, не маю кращих варіантів. Hugo вміє все, включаючи самостійно збирати JS/CSS та обробляти зображення. Попри всю цю потужність, в мене гальмувала робота над оновленням сайту. Поміркував та зрозумів, що це через брак зручного середовища розробки.

Hugo використовує шаблони Go - звичайні html/template. Акуратний HTML і так не легко підтримувати, а коли в нього домішують теги шаблонізатора, то взагалі. (Або це я зіпсований роками роботи з JSX, який форматується з математичною точністю.)

Втім, все вирішується гарними інструментами. Дізнався, що тепер в Prettier є плагін prettier-plugin-go-template, який зокрема вміє форматувати й шаблони Hugo. Цікаво, що для того шаблон повинен мати “збалансовану” вкладеність, тобто, наприклад не можна робити {{if .x}}</div><div>{{end}}. А Prettier в мене вже був, для TypeScript та для Markdown - тепер розширив його обовʼязки.

Далі, певно, потрібно не забувати про стандартні засоби боротьби зі складністю: розділяти код на файли, узагальнювати повторювані місця. З одного боку, шаблони Go все це вміють, а з іншого, в Hugo вже й так складна система вибору шаблону — хоч здається, що типів сторінок не так багато, але є ще “архетипи” постів, та для кожного з них різні сторінки переліків, а ще є сторінки категорій та тегів… і все це повинно працювати синергійно. Принаймні сервер розробки дійсно зручний та навіть перезавантажує сторінки автоматично.

Ще є скрипти, що виконуються на сервері. Звісно, це вже не Hugo, бо він тільки робить статичний сайт — а Vercel, Netlify, Cloudflare Workers чи що там у вас. Але локально сервер розробки вміє інтегрувати їх в сайт десь так само, як і хостинг. Для того є конфігурація redirects; звісно, сам сервер зі скриптами доведеться запускати окремо, може, утилітою goreman.

🏷️ Сьогодні дійшли руки додати до каналу теги - бо постів вже за 800, та регулярно виникає потреба послатися на ту чи іншу серію. Також це допоможе SEO.

Відразу натрапив на проблему. В мене ж пости йдуть на сайт через Hugo та в Телеграм. В Телеграмі теги робляться тривіально: додаєш до слова октоторп та він сам робить посилання на пошук за цим словом. У Hugo система в корні інша: теги належать метаданим поста, а не тексту, та на знаки решітки йому ніяково.

(Тривіальне рішення, певно, це писати тег і в метадані, і в текст, та закрити очі на зайві решітки на сайті. Але хіба це може задовольнити?)

Спочатку хотів зробити якийсь тег-шорткод, на кшталт того що маю для внутрішніх посилань. Це ніби працювало б, але в вихідному коді неохайно (особливо порівняно з хештегом!) та технічно складно.

🚿 Тоді сходив в душ та винайшов елегантне рішення: теги будуть в метаданих, а в тексті я буду автоматично додавати тег до першої згадки слова. Або, коли такої згадки немає, просто в перший рядок. Що й зроблено в цьому пості.

Окрема історія - що в Телеграмі складніше ретроактивно додати теги… якби я це робив вручну. Але оскільки для того є бот, який побачить зміну змісту та відредагує пости, то це можна зробити практично без зусиль… якщо нічого не поламається.

Взагалі я, звісно, переписував колись блог на новий рушій. Коли я починав щось публікувати, здається, ще взагалі “рушіїв” ніяких безплатних не було, а платити тоді не було чим. Перший сайт був на рукописному HTML.

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

На початку 2008 в мене зʼявився перший віртуальний сервер, а також перша версія блогу на WordPress. Не памʼятаю, як обрав саме його. Я на той час працював на PHP та й фрілансив для WordPress, тож, мабуть, тому. Здається, в мене була власна тема та чомусь багато всього складного… Хоча найбільший мінус WordPress як я бачу зараз це його вразливість. Для найпопулярнішої платформи в інтернеті, в ній надто багато дірок, чим без кінця користуються спамери. Сайт на WordPress потребує постійної уваги та оновлень. Або просто будеш інколи помічати, що вже пару місяців хтось розсилає пошту з твого VPS/

Іронія в тому, що в тому самому 2008 я почав дивитись на RubyOnRails, а невдовзі й працювати з ним професійно… тож підтримка WordPress подобалася ще менше. Я не знайшов нічого кращого, ніж у 2011 переписати все на Rails.

З плюсів — ламати припинили, код став приємніше (HAML/SASS, між іншим). Блог перетворився на справжній проєкт-хобі. З мінусів - Ruby on Rails значно ненажерливіше. Особливо коли не розробляти сайт з розрахунком на кешування повних сторінок. Бо, якщо чесно, якщо кешувати, то недалеко від наступного рішення…

У 2016 мені набридло підтримувати Rails, та я переписав блог на Hugo - щоб він знову став статичним сайтом. Бо, дійсно, від блогу одного автора не потрібно багато динамічності. До речі, статичність не означає, що в сайті відсутня логіка та програмування; їх тут повно — але весь код виконується в момент компіляції. Головне, від чого довелося позбавитися — це коментарі — а точніше, замінити на зовнішнє рішення. Спочатку на Disqus, а зараз на власний скрипт. Втім, коментарі на сайтах все одно відійшли в минуле.

(Також, очевидно, зникла адміністративна панель та вебредактор. Тут я не бачу проблем, бо на розробку гідної адміністративної панелі часу не вистачало — а у статичного сайту замість неї звичний IDE та Git.)

Виходить, блог я переписував двічі: спочатку на Rails, а потім — з них. За цим трендом у 2023 пора було переписувати наново. Але, я переконаний, що статичний сайт — це найкраще рішення для мене, тому нікуди не поспішаю.

Додав до сайту підтримку тегів. Нарешті можу скинути посилання на серію про основи безпеки в Інтернеті — проміж інших, одна з моїх улюблених. Також можна насолоджуватись хмарою тегів, хоча я тільки почав її наповнювати.

Трохи нюансів. Я хотів теги для каналу окремо від інших розділів сайту. Знайшов, як це роблять, на форумі. Якщо без деталей, то такі теги треба робити окремою таксономією, назвати її stendap/tags - і тільки так, бо ця назва стає шляхом в URL. Але також тепер в метаданих поста теж треба писати "daily/tags", що вже дуже дивно виглядає. Зате результат досягнений.

Хмару тегів в наш час легко зробити з CSS, як ось тут пояснюють. Тільки там кожному тегу призначається клас розміру, а я його обчислюю на ходу з кількості постів. Ще залишається нормалізувати її відносно максимальної, що звучить просто, але в шаблонах Go арифметики немає, а є тільки виклики функцій, та ще й в Польській нотації: font-size:{{add 1 (mul $pageCount $multiplier)}}em.

Ну і ще придумав на сторінці тегу показувати повні пости, але щоб легше було зорієнтуватись, додати також табличку зі змістом. А табличка вже була готова, бо в статтях на сайті вона зʼявляється, коли достатньо заголовків. Тож залишалось тільки адаптувати.

Мій бот скрипт для каналу — який бере зміст з файлів блогу на Hugo - був з самого початку збудований як повністю окреме рішення: він сам знаходить пости, сам їх парсить, сам їх надсилає в Telegram. З Hugo в нього спільні тільки домовленості про структуру тек та формат файлів.

Нещодавно мені спало на думку, що взагалі-то перші два кроки Hugo теж робить, та незрівнянно вправніше. Тому гарно було б якось включитися в Hugo та залишити на власний скрипт тільки публікацію. Зокрема, це розблокувало б інші напрямки публікації, бо наразі скрипт дуже завʼязаний на Telegram та розділити його мені поки не вдалося.

Механізму плагінів в Hugo немає, тож що я придумав: Hugo під час збірки буде генерувати мені JSON з всіма даними, що потрібні для публікації, а скрипту залишиться зчитати JSON та, так би мовити, “синхронізувати” його в канал.

…Механізму “згенерувати JSON” в Hugo теж немає. Зате ми можемо створити окрему сторінку, а в її шаблоні назбирати даних, викликати для них jsonify та надрукувати — от і буде JSON. На щастя, принаймні з кожної сторінки є необмежений доступ до даних сайту.

Величезний мінус — збирати дані доведеться всередині шаблону. Hugo використовує звичайні шаблони Go, але ніколи в Go мені не спадало на думку, скажімо, перетворювати в шаблоні масиви даних. Бо мова шаблонів незручна, не має підказок IDE, та ще й документація Hugo неповноцінна (в документації функції називаються, як в Go, а в шаблонах пишуться за псевдонімами, яких у переліках функцій та навіть в пошуці не видно).

Але, попри все це, мені вдалося! Найбільше часу витратив на спроби функціонального перетворення масивів — бо там наче є функція apply - аналог map - але виявилося, що дуже обмежена. А мова шаблонів — все ж імперативна. Тому, наприклад, щоб перетворити масив тегів-обʼєктів у масив назв, я оголошую новий масив та циклом складаю в нього назви. Коли це збагнеш, решта вже не так складно.

Так що чекайте в наступні тижні покращень по скрипту публікації, а може й публікації самого скрипту.

Як і планував, нова версія вже у TestFlight. Також нарешті дістався до створення сторінки для застосунку: ping.leonid.codes. Поки сторінка майже порожня, але на з цим продуктом є стимул її розвивати.

Саму сторінку я скопіював із останньої такої задачі. Взагалі гарно б було натренуватись робити мінісайти для (менших) проєктів, бо інакше вони часто залишаються без всякого маркетингу.

А маркетингу воно знаєте, скільки потрібно? Ще б дорожню карту кудись викласти, та сторінку в соціальних мережах вести, та хоч мінімальний, але набір статей з поясненнями. Та відео використання. В мене традиційно немає на то хисту, а коли і є хист, то немає часу.

Про час: відзначу, що розгортування на Cloudflare Pages зайняло лише пару хвилин. Це з урахуванням того, що мій домен вже під Cloudflare. Бо завдяки цьому він сам робить всі налаштування, достатньо підʼєднати репозиторій та вказати піддомен.

Сьогодні зробив (не без допомоги Claude, зізнаюся) пошук по каналу. Вже кілька років про це думаю, але, знаєте як — пошук це велика задача, ніколи не було часу. А тут за півдня зміг зробити непогану версію, яку можна побачити прямо на сторінці каналу. (Шукайте рядок пошуку.)

Будь-який повнотекстовий пошук спочатку будує індекс, а потім шукає по ньому. Колись в мене на сайті вже був пошук, чисто фронтендовий, через Lunr.js - там індекс сидів прямо в коді скрипту. Втім, це значило, що для пошуку доводилося завантажувати кілька мегабайтів — фактично, весь зміст сайту. Це мені не подобалося. А окрім того, Lunr більше не підтримується.

Тож шукав рішення із бекендом. В Hugo є офіційний перелік, з яких я зупинився на Orama, бо вони обіцяли рішення на чистому JavaScript. (А ще Orama вміє векторизувати запити, що дає можливість шукати по синонімах — але тут поки проблеми.) Нагенерувати базовий код для Orama допоміг Claude, тож не довелося починати з нуля.

Моє рішення складається із чотирьох частин. Спочатку, під час побудови сайту Hugo генерує зміст JSON. Це для мене вже знайомий крок, бо так само працює OmniWOPE.

Потім, теж в скрипті постачі, запускається окремо індексатор. Він перебирає вхідний JSON та генерує величезний (22 Мб!) JSON індексу. Цей файл потрапляє в збірку серверних функцій Vercel.

Далі є функція /search - вона завантажує той індекс з файлу та викликає пошук Orama — це вже досить прямолінійна дія.

Та нарешті, є фронтенд, який теж нагенерував Claude, бо мені не хотілося довго возитися із шаблонами. Фронтенд робить запити до API та виводить список результатів. Попросив Claude “no frameworks, use HTML DOM API” та в цілому отримав те що хотів. Потім додав “use css classes and html tags from post list page”, бо на початку він наробив власних стилів. Якось так.

Поки в цього пошуку є обмеження. Не знайшов, як в Orama мати документи різними мовами — тому поки є тільки українською. Пейджинацію поки не став робити. Але головне — що нарешті закрив навіть власну потребу, бо часто я банально не міг знайти статтю простим пошуком (їх, до речі, тільки-но перевалило за тисячу!). А Google чомусь надзвичайно погано індексує. (Треба і з цим ще помучитись.)