Виджет в папке widgets/ этой темы — одно из двух.

Статичный — только figure.html, и больше ничего. Он рендерится один раз, на сборке, и остаётся таким навсегда; передавать эстафету некому — своего widget.js у него нет. Вот весь виджет ниже:

Интерактивный — widget.js, который регистрирует себя через Taiga.widget(id, fn), обычно в паре с figure.html, который держит место до запуска JS, и widget.css — на то, чего не хватает готовым классам темы (.w-row/.w-btn/.w-num/.w-cap):

Оба — один и тот же шорткод {{< widget id="…" >}} без тела внутри — одного id достаточно, чтобы шорткод сам пошёл искать widgets/<id>/figure.html как ресурс страницы для монта. Другую форму — фолбэк прямо внутри шорткода — смотри в «Гайд — это папка».

#Слой _shared

Оба виджета выше подгружают widgets/_shared/lib.js и widgets/_shared/shared.css раньше своих собственных файлов — сборка сортирует все widgets/**.js и widgets/**.css бандла по имени, а _shared идёт раньше любой папки w-*. В этом бандле конкретно:

• _shared/lib.js держит единственный guard (var W = window.Taiga; if (!W || …) return;), на который опирается каждый widgets/<id>/widget.js бандла, плюс крошечный хелпер h(), который w-anatomy-toggle/widget.js вызывает без импорта и без повторного объявления — все файлы склеиваются в один скрипт и делят одну область видимости.
• _shared/shared.css держит .wa-tag — маленькую пилюлю, которой оба виджета выше подписывают имя файла. Она попала в _shared по самой непримечательной причине: её реально используют два виджета на этой странице.

Здесь ничто не разделено по необходимости — бандл с одним виджетом вполне мог бы держать guard прямо в widgets/<id>/widget.js. Разделение сделано нарочно, чтобы у страницы было на что показать _shared/. Бандл, где разделение действительно оправдано, выглядит так же по форме, только тяжелее: общий движок и его таблица спецификаций лежат в _shared/lib.js, а у каждого id, который этот движок обслуживает, — своя папка widgets/<id>/ под то, что реально принадлежит только ему: фигуру, переопределение в widget.css, а иногда и вовсе ничего.

#Читаем исходники

Весь бандл, рядом с этим файлом:

widget-anatomy/
  index.md, index.ru.md    ← этот текст на обоих языках
  widgets/
    _shared/
      lib.js               ← guard + хелпер h()
      shared.css            ← .wa-tag
    w-anatomy-static/
      figure.html           ← весь виджет — без widget.js
    w-anatomy-toggle/
      figure.html           ← фолбэк без JS
      widget.js             ← Taiga.widget('w-anatomy-toggle', …)
      widget.css             ← .wa-hl, класс только этого виджета

Любой файл в widgets/ необязателен — кроме тех, что дают виджету суть: статичному id нужен figure.html, интерактивному — widget.js, и любой может добавить widget.css. Виджет может и вовсе обойтись без figure.html, начав с пустого монта — именно так устроен w-ks-counter на странице «Kitchen sink».

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

#Панели и минимапы

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

#Поповер «Вид»

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

#Что запоминается

Все настройки живут локально в браузере — без аккаунтов и без сети:

Очистка site data браузера возвращает всё к дефолтам — это штатный способ «сбросить настройки».

Фирменный цвет сайта — это toml-файл в data/themes/ на стороне сайта:

name = "Моя"      # имя в пикере
weight = 80       # позиция в списке пикера

"bg-deep" = "#101418"
"bg-surface" = "#1a2027"
"text-primary" = "#d8dee6"

Hugo мержит данные темы и сайта (при совпадении имён побеждает сайт), поэтому файл сам попадает и в CSS, и в пикер палитр в шапке. Не нужна палитра из комплекта темы — переопредели её файл с disabled = true, и она исчезнет отовсюду. Как из toml получаются CSS-блоки и свотчи — разобрано в «Палитра — это один файл».

#custom.css и хуки

Точечные правки поверх палитры — assets/css/custom.css сайта: если файл существует, тема подключает его последним в CSS-бандл, так что твои правила побеждают без !important. Дизайн-токены — публичный API: имена CSS-переменных стабильны и перечислены в docs/customizing.md темы.

Для аналитики, своих meta-тегов и сторонних скриптов есть hooks-партиалы: hooks/head-extra.html и hooks/foot-extra.html в теме пустые, сайт кладёт одноимённые файлы в свой layouts/_partials/ — и их содержимое попадает в head и в конец body. А если нужно поменять сам рендер — любой партиал темы переопределяется одноимённым файлом сайта: lookup order Hugo всегда предпочитает файлы сайта. Мелкие именованные партиалы — логотип, футер, карточка ленты — существуют ровно для такого точечного переопределения.

#Свой раздел

Понадобился раздел, которого в теме нет, — глоссарий, каталог, песочница с тренажёром. Для него не нужны ни новый layout, ни правки темы: это обычная страница или бандл, а интерактив — те же widgets.js рядом с текстом, механизм работает для любого бандла, не только для гайдов. Пункт меню добавляется в [[menus.main]] конфига; параметр params.badge = "β" у пункта рисует бейдж — это генерик-фича навигации, а не признак особого раздела.

На этом демо так собрана «Песочница»: в теме от неё нет ни следа, весь раздел — три файла на стороне сайта.

#Свои строки

Тексты интерфейса не захардкожены в шаблонах. Серверные строки живут в i18n/*.toml: сайт кладёт свой файл с частичным набором ключей, и он мержится с файлом темы — переопределяешь только нужное. Строки, живущие в JS — поповер «Вид», подсказки минимап, — переопределяются объектом window.THEME_I18N; список ключей — в docs/customizing.md.

#Второй язык

Добавление языка — аддитивный шаг, а не миграция. В конфиг дописывается блок [languages.en] (плюс [languages.en.params] для hero-строки и [languages.en.menus] для меню). Переводы — суффиксами файлов: index.en.md рядом с index.md, включая _index рубрик и серий; Hugo связывает версии сам. Переключатель языков появляется в шапке, когда языков больше одного, а Pagefind строит отдельный индекс на каждый язык по lang страницы. Правок шаблонов — ноль; пошаговый чеклист — в docs/i18n.md темы.

Теперь ты можешь увезти сайт сколь угодно далеко от этого демо — не форкая тему.

#Что дальше

Руководство на этом закончено: тема стоит, гайды пишутся, сайт выглядит по-своему. Если интересно, почему это устроено именно так, — в «Устройстве» есть серия «Анатомия темы»: папка-бандл, арифметика серий, палитры-как-данные. А все компоненты разом собраны на полигоне в «Справочнике».

hugo new content guides/my-first --kind guides

Архетип guides создаёт папку-бандл: index.md с заполненным каркасом front matter и заготовку widgets.js рядом. Файлы, которые лежат в папке гайда, тема подхватывает сама — подключать ничего не нужно.

#Front matter: что заполнять

title: "Мой первый гайд"
description: "Одно предложение — для ленты, поиска и meta."
lead: "Лид-абзац под заголовком; может быть длиннее description."
tags: [example, setup]
mins: 4
version: "v0.0.1"

Подсвечены два поля с неочевидными правилами. mins — рукописная честная оценка времени чтения: она попадает в чипы статьи и в арифметику серии, поэтому автоподсчёту не доверяется (опустишь поле — тема посчитает сама). version — произвольная строка чипа версии: версия языка, СУБД, твоего продукта — тема рендерит её как есть. Поля date и slug архетип тоже проставит; дата живёт только в ленте и RSS — в тексте статьи она не появляется нигде.

Частью серии гайд становится по расположению: его папка лежит внутри папки серии (guides/track/my-part/), а порядок среди частей задаёт weight; короткое имя для панели — rail_title. Как из этого получается «часть N из M», разобрано в «Серия знает о себе всё».

Заголовки размечай с явными якорями: ## Секция {#section-id}, латиницей — тогда ссылки и оглавление не зависят от транслитерации кириллицы.

#Шорткоды

Четыре, которых хватает на большинство гайдов:

• callout — врезка; типы key, trap, internals, note;
• widget — точка монтирования живой иллюстрации (ниже);
• raw — многострочный HTML-фрагмент как есть, для диаграмм;
• bigcard — крупная ссылка-карточка на соседний материал.

{{< callout type="trap" label="Ловушка" >}}
Внутри — обычный markdown.
{{< /callout >}}

У код-блоков есть атрибуты прямо в фенсе: ```toml {label="config.toml (фрагмент)", hl_lines=[2]} — label рисует подпись над блоком, hl_lines подсвечивает строки. Оба уже встречались в этой статье: подпись у каждого блока и подсветка в примере front matter сделаны именно так.

#Виджет за два касания

Живая иллюстрация добавляется без правки темы. Касание первое — шорткод в тексте; внутрь кладётся статичный фолбэк, который останется у читателей без JS:

{{< widget id="w-demo" note="— задание читателю" >}}
<p>Статичный фолбэк для читателей без JS.</p>
{{< /widget >}}

Касание второе — инициализатор с тем же id в widgets.js рядом с index.md:

Taiga.widget("w-demo", function (root) {
  root.innerHTML = "";
  // строишь виджет из строительных классов темы:
  // .w-row, .w-btn, .w-num, .w-cap — свои стили не нужны
});

Рантайм темы дождётся DOM, найдёт точку монтирования и вызовет колбэк в try/catch: упавший виджет напишет в консоль и не уронит страницу. Следи только за тем, чтобы id в шорткоде и в Taiga.widget(…) совпадали буква в букву.

Вот работающее доказательство — прикидка честного mins для будущего гайда:

Он собран ровно как в примерах выше: шорткод — здесь, Taiga.widget("w-mins", …) — в widgets.js в папке этой статьи.

Теперь ты можешь написать гайд с живой иллюстрацией, не открыв ни одного файла темы.

#Что дальше

Гайд есть, сайт собирается — но выглядит он пока как это демо, а не как твой проект. Третья часть — про палитру одним файлом, custom.css, собственные разделы и второй язык.

Тема для учебных гайдов, которые читают подряд, а не вразброс. Контент раскладывается в три уровня: рубрики → серии → гайды. Серия — это папка внутри рубрики: членство определяется тем, где лежит гайд; всё остальное — «часть N из M» в кикере, панель-оглавление слева, мост с «осталось ~N мин» внизу — считается на сборке. Гайд — это папка: рядом с текстом лежат его интерактивные виджеты, стили и обложка, и переносится он целиком, одной папкой. Всё, что видно на этом демо, — лента, поиск, палитры, генерация обложек — штатные механизмы темы: само демо собрано на ней же.

Из инструментов нужны два бинаря. Первый — обычный hugo, не extended: Sass в теме нет, а esbuild для JS встроен в стандартный бинарь. Второй — pagefind, полнотекстовый поиск по собранному сайту. Node, npm и node_modules не участвуют ни в сборке, ни в разработке. Минимальная версия Hugo объявлена в конфиге темы: слишком старый бинарь остановит сборку с внятной ошибкой, а не со странным поведением.

#Три способа установить

Пути ниже — плейсхолдеры: подставь адрес репозитория темы.

Hugo Module — основной способ. В конфиг сайта:

[module]
  [[module.imports]]
    path = "github.com/user/theme"

Затем hugo mod get -u (если сайт ещё не модуль — один раз hugo mod init github.com/user/site). Версии резолвятся по semver-тегам темы; для локальной правки темы — replace в go.mod сайта.

Git submodule — если модули не хочется:

git submodule add https://github.com/user/theme themes/theme

и theme = "theme" в конфиге. В CI не забудь checkout с submodules: recursive.

Копия в themes/ — клон или распакованный архив в themes/theme плюс тот же theme = "theme". Обновления руками; зато способ годится, чтобы просто посмотреть тему без обязательств.

#Минимальный конфиг

baseURL = "https://example.org/"
title = "Мой учебник"
theme = "theme"                # не нужен при установке модулем
defaultContentLanguage = "ru"

[languages.ru]
  languageCode = "ru"
  languageName = "Русский"
  weight = 1

[taxonomies]
  tag = "tags"

[[menus.main]]
  name = "Гайды"
  url = "/guides/"
  weight = 10

Блок [languages.ru] выглядит лишним, пока язык один, но он делает добавление второго языка аддитивным шагом, а не миграцией конфига. Остальное поведение настраивается через [params] — hero-строка главной, число видимых постов ленты, «гайд недели», палитра по умолчанию, — и у всего есть дефолты: сайт собирается и без единого параметра. Полный реестр — в docs/params.md темы.

#Структура контента

content/
├── _index.md              # главная: hero-строка и данные
└── guides/
    ├── _index.md          # рубрика: label, lead
    ├── my-first/
    │   └── index.md       # одиночный гайд = папка (leaf bundle)
    └── track/             # серия = подпапка рубрики
        ├── _index.md      # метаданные серии: title, description
        └── part-one/
            └── index.md   # часть — та же папка гайда, уровнем глубже

Имена секций — свои: тема оперирует «секциями», «сериями» и «гайдами» и не хардкодит ни названий рубрик, ни предметных слов. Учебник про базы данных и учебник про акварель раскладываются одинаково.

#Собрать

hugo server                        # разработка
hugo && pagefind --site public     # прод: сайт + поисковый индекс

Команд две, потому что pagefind строит индекс по уже собранному сайту. В dev без индекса поиск не ломается: модалка тихо подсказывает, какой командой он собирается.

Теперь ты можешь развернуть сайт на теме с нуля и собрать его в один прогон — осталось его наполнить.

#Что дальше

Пустой сайт собирается, но показывать пока нечего. Следующая часть — про первый гайд: каркас одной командой, канон front matter и живой виджет за два касания.

Второго уровня — с решёткой #, третьего — с ##. Инлайн: курсив, жирный, код, внутренняя ссылка на эталонный гайд.

##Подзаголовок третьего уровня

Проверяем, что render-heading вешает ## и якорь на h3.

#Код

Go подсвечивается сервером (Chroma в цветах палитры):

type Point struct {
	X, Y int64
}
func dist(a, b Point) int64 { return (a.X-b.X)*(a.X-b.X) }

С подписью файла и подсветкой строки ({label=… hl_lines=[2]}):

func mallocgc(size uintptr) unsafe.Pointer {
	c := getMCache()          // горячий путь — без блокировок
	return c.alloc(size)
}

Остальные подсвеченные языки носят те же роли — синий у структурного имени, медный у числа, свой тон у строк, приглушённый курсив у комментария:

{
  "items": [
    {"price": 123, "shipped": true},
    {"price": 101}  // хвостовой комментарий допустим
  ]
}

export GODEBUG=schedtrace=1000
go build ./... && ./app --addr "$HOST:8080"   # либо всё, либо ничего

Голый забор, text и txt — плоская форма, .nohl: она и нужна выводу команды:

$ go build ./...
ok  taiga/internals  0.312s

#Таблица

Markdown-таблица, обёртку .tbl-wrap вешает render-table:

#Коллауты

#Fold

Сворачиваемая врезка — значок, заголовок и переключатель; панель выезжает по высоте. title= — инлайновый Markdown, тело — Markdown.

func main() { println("hello") }

Примерно за полэкрана текста кат сам меняет регистр: заголовок набирается читательским кеглем, блок получает свой воздух, а панель закрывается явной кнопкой — длинное отступление можно свернуть там, где кончилось чтение. size= задаёт регистр принудительно; здесь — чтобы показать секцию, не вставляя стену текста.

#Термины

Наведи на подчёркнутое слово — определение раскроется карточкой; клик её закрепит, чтобы можно было спокойно читать и уйти по ссылке. Без JavaScript все определения лежат списком в конце страницы, и каждое слово ведёт к своему.

Простейшая форма — слово и определение, тип по умолчанию: у каждого P есть свой mcache, и попадание в него — самый дешёвый путь аллокации.

С ярлыком и цветом типа, и с ссылкой в подвале карточки: компилятор вставляет барьер записи — и именно поэтому у записи указателя цена выше, чем у записи int.

Тело определения проходит тот же конвейер, что и статья, поэтому листинг внутри карточки подсвечен ровно так же, как был бы в прозе: путь пишется как JSON Pointer, а не как путь через точки.

Слово в тексте склоняется, а шапка карточки — нет; для этого title=: данные лежат в кэшах ядра, а не в оперативке.

#Диаграммы

Диаграмма памяти и байтовая лента — сырой HTML через {{< raw >}}:

#Виджеты

Форма 1 — пустой mount, оживляет Taiga.widget из widgets.js:

Форма 2 — mount со статик-фолбэком внутри (виден без JS):

Форма 3 — без id, произвольный HTML прямо в figure:

#Карточка

#Превью ссылок

На точном курсоре наведи на любую ссылку ниже — появится карточка-превью: физика терм-карточки, один поповер, собранный из билд-фрагмента (внутренние ссылки) или из пререндеренной карточки (Telegram, YouTube).

Внутренние ссылки открывают окно в страницу: превью целого гайда, якорь на раздел, который сужает карточку до одного раздела, и оглавление серии со списком частей.

Telegram — пост из авторского канала получает карточку, собранную на билде: пост 409 и пост 410. Несуществующий пост деградирует до карточки канала, а чужой канал получает только значок ✈, без карточки.

YouTube — доклад про планировщик Go открывает видео-карточку с превью-кадром, длительностью и числом просмотров.

Обычная внешняя ссылка несёт только значок ↗.

Википедия — work-stealing планировщик и вытесняющая многозадачность открывают карточку-сводку из REST API Wikimedia, со значком W.

Блог Go — превью области видимости переменной цикла и классический error handling in Go открывают карточку с курсивным значком Go, байлайном и зачином поста.

#Рассылка

Блоки подписки — на сайте, где рассылка включена (params.newsletter.enable, см. newsletter.md). За ними в демо нет эндпоинта, поэтому отправка заканчивается состоянием ошибки — на неё как раз и стоит посмотреть.

Срединный блок, поставленный руками, с крестиком (dismiss=), решение по которому запоминается по блоку:

Голая форма для страницы, написанной прозой (newsletter-inline) — тот же компонент, что стоит на странице подписки:

Карточка в подвале этой страницы — третий вариант, newsletter-cta; здесь её вставил автоматически placements.articleEnd.

Наивная модель: обложки для шаринга рисуют руками. На тридцатой статье это боль, а после переименования заголовка — боль вдвойне: картинка теперь врёт, перерисовывай.

Здесь обложки генерирует сборка, а внешний вид описывает стиль — папка в assets/og/, имя папки = ключ стиля. Внутри два обязательных файла: base.png — подложка 1200×630, где живёт вся графика, и layout.toml — раскладка текстовых блоков поверх неё:

[[block]]
text = "{title}"
font = "Inter-ExtraBold.ttf"
size = 66
color = "#e6dfd2"
x = 76
y = 270
width = 1010     # автоперенос длинных заголовков

Плейсхолдеры — {title}, {kicker}, {meta}, {domain}, {part} — собирает партиал, так что стиль языко-нейтрален: тексты приходят из статьи, раскладка — из стиля. Блоки рисуются по порядку; неизвестные ключи игнорируются — старый стиль переживёт новую версию темы. Опциональный home.png — полностью запечённый постер для главной и рубрик; если его нет, общая обложка генерируется тем же пайплайном из base.png. А папка без layout.toml стилем просто не считается.

Выбирается стиль параметром сайта ogImages.style, для отдельной страницы — og_style во front matter. А поверх любого стиля работает авторский оверрайд: положи og.png в бандл статьи — и генератор уступит место твоей картинке. Свой стиль сайт добавляет папкой: ассеты темы и сайта мержатся, сайт побеждает.

#Поиск, который читает всё

Наивная модель поиска на статике — индекс из заголовков и описаний: он найдёт статью по названию и промолчит про термин из середины текста. Здесь движок другой: Pagefind строит полнотекстовый индекс по уже собранному сайту. Поэтому сборка — две команды:

hugo && pagefind --site public

Pagefind — standalone-бинарь, Node не нужен. Он проходит по готовому HTML и берёт только то, что размечено темой: тело статьи — целиком, крошки и минуты для карточки результата — отдельными метаданными, а панели, виджеты и прочий хром в индекс не попадают вовсе. Код-блоки индексируются с пониженным весом: поиск по имени функции обязан работать, но код не должен забивать выдачу. Русская морфология — из коробки, по языку страницы: запрос «обложек» найдёт «обложка». Скрипт поиска и сам индекс грузятся лениво, при первом открытии модалки: пока не искал — не скачивал ни байта.

Проверь на этой странице: открой поиск и набери слово из середины текста — например, «кегль». Найдётся, с подсветкой и выдержкой. А если запустить голый hugo server без второй команды, модалка честно подскажет, чем индекс собирается, — тихо, без красных ошибок.

#Чип версии

В мете этой статьи стоит чип «v0.0.1». Тема понятия не имеет, что это значит: чип — произвольная строка из version во front matter, а если поля нет — из versionDefault сайта. Сайт про язык программирования напишет туда версию языка, сайт про базу данных — «PostgreSQL 17», а это демо пишет версию самой темы — и тема рендерит всё одинаково, как есть. Маленькая деталь, но именно из таких складывается агностичность: тема не знает, о чём твой сайт.

Теперь ты можешь собрать сайт с обложками и полнотекстовым поиском двумя командами — и объяснить, почему команд именно две.

#Что дальше

Это был взгляд снаружи — что сборка делает для читателя. Взгляд изнутри — как устроены сами страницы — в серии «Анатомия темы»: про папки-бандлы, арифметику серий и палитры-файлы.

Наивная модель: хочу перекрасить сайт под себя — открою CSS темы и поменяю цвета. Боль наступает при первом же обновлении темы: твои правки лежат в её файлах, и каждый апдейт — это merge-конфликт. Классический выбор «форкни и отстань от апстрима — или терпи чужие цвета». Оба варианта плохие, и оба растут из одной ошибки: цвет считается оформлением, хотя на самом деле это данные — таблица «имя переменной → значение», которой просто негде лежать, кроме чужого CSS.

#Один toml

Здесь палитра — это данные, а не стили. Каждая — файл data/themes/<id>.toml: пара служебных полей плюс цветовые переменные, у которых ключи — буквально имена CSS-переменных без --:

name = "Моя"      # имя в пикере
weight = 80       # позиция в списке пикера

"bg-deep" = "#101418"
"bg-surface" = "#1a2027"
"border" = "#2b3138"
"text-primary" = "#d8dee6"

Подсвечены единственные две строки, которые не являются CSS-переменными. Всё остальное — прямая таблица «имя → цвет». Ключевые из них:

На сборке партиал head/palettes.html превращает эти файлы в CSS: блок :root { … } для палитры по умолчанию плюс по блоку [data-theme="<id>"] { … } на каждую — и вливает результат первым в общий CSS-бандл. Какая палитра дефолтная — решает параметр сайта defaultTheme: это просто id одного из файлов. Переключение темы — смена одного атрибута data-theme на <html>; каскад делает остальное. Поэтому же смена мгновенная: браузеру не нужно ничего дозагружать, все палитры уже в CSS, который он получил с первым байтом страницы.

#Пикер и его JSON

Откуда пикер знает, какие палитры есть? Из тех же данных: партиал кладёт на страницу <script type="application/json" id="dg-themes"> со списком {id, name, group, weight, свотч-цвета} — свотчи собираются из четырёх фиксированных ключей палитры (bg-deep, bg-surface, text-primary, text-muted), так что миниатюра в пикере честно показывает будущий холст, карточку и текст. Поповер в шапке читает этот список и рисует кнопки. Виджет ниже читает тот же самый список — и по клику ставит тот же самый атрибут:

Заметь честную разницу: виджет меняет только атрибут, а пикер ещё и записывает выбор в хранилище — поэтому после перезагрузки победит его версия. И применяется сохранённый выбор до первой отрисовки, крошечным инлайн-скриптом в <head>: страница ни на кадр не вспыхивает дефолтной палитрой.

Теперь главное — расширяемость. Сайту нужна фирменная палитра? Положи data/themes/mine.toml на стороне сайта: Hugo мержит данные темы и сайта (сайт побеждает при совпадении имён), и файл сам попадёт и в CSS, и в пикер. Не нравится палитра из комплекта темы — переопредели её файл с disabled = true, и она исчезнет отовсюду. Ни строчки в теме, ни форка.

Теперь ты можешь добавить сайту собственную палитру одним файлом — не трогая ни CSS, ни JS, ни шаблоны темы.

#Что дальше

Серия «Анатомия темы» на этом закончена: гайд — папка, серия — папка гайдов, палитра — файл. Всё показанное — и десяток компонентов, до которых мы не дошли, — собрано на одной странице-полигоне:

А про то, что происходит на сборке — обложки, поиск, чип версии, — есть отдельный разбор в «Приёмах».

Наивная модель: серия — это когда в конце каждой статьи стоит список ссылок на остальные. Работает ровно до второго изменения. Добавил четвёртую часть — иди обнови три старых статьи. Переставил части местами — «часть 3 из 7» в заголовках теперь врёт, и хорошо, если ты вспомнил про все семь. Оглавление, размазанное по статьям, устаревает в момент любой правки — потому что источников правды столько же, сколько частей.

Хуже того: половина серийной механики вообще не выражается ссылками руками. «Осталось ~9 минут до конца серии» — это арифметика по всем частям сразу; ни одна статья в одиночку такого про себя не знает.

#Папка, а не поле

Здесь у серии один источник правды. Часть почти ничего о себе не объявляет — она просто лежит в папке серии, под-секции рубрики:

content/inside/
  anatomy/                  ← серия
    _index.md               ← метаданные серии: title, description, порядок
    guide-is-a-bundle/      ← часть, weight: 10
    series-knows-itself/    ← часть, weight: 20 — ты здесь
    palette-is-a-file/      ← часть, weight: 30

Это папка статьи, которую ты сейчас читаешь, — можешь сверить с кикером над заголовком. Членство — это расположение; единственное, что часть несёт сама, — weight во front matter, её порядок среди частей. Всё остальное вычисляется на сборке: части сортируются по weight, номер «N» — позиция в отсортированном списке, «M» — его длина. Заметь: порядок задаёт вес, а не даты публикации — переставить части местами можно, не переписывая историю ленты.

Из того же отсортированного списка собирается всё серийное на странице. Кикер склеивается из трёх независимых источников: метка рубрики (front matter секции), заголовок серии (front matter её _index.md) и вычисленное «часть N из M». Панель слева — оглавление с отметкой текущей части. Мост внизу — соседи prev/next плюс шкала прогресса. Один список — четыре потребителя.

Вот как выглядит наша серия глазами сборки:

Подсвеченная ячейка — статья, внутри которой ты находишься. Наведи на соседние: у каждой в тултипе её вес и минуты.

Заголовок серии, описание и порядок на странице рубрики — тоже не магия: это front matter _index.md её папки — здесь это content/inside/anatomy/_index.md (каркас создаётся командой hugo new content inside/anatomy/_index.md --kind series). Тот же файл даёт серии лендинг по адресу /inside/anatomy/: заголовок с тэглайном, описание, тело самого файла как эпиграф, список частей и кнопку «начать серию». Ссылки «вся серия» в панели и мосте ведут именно туда; на странице рубрики та же серия стоит блоком с якорем. А серия, анонсированная _index.md без единой части, — не ошибка: рубрика покажет её тизером «готовится», а лендинг отрендерит анонс.

#Проверь арифметику

Формула моста настолько короткая, что её можно пересчитать прямо здесь. Виджет ниже гоняет ту же логику по числам этой самой серии:

Заметь: числа в виджете совпадают с диаграммой выше и с настоящим мостом внизу страницы. Так и задумано — источник у всех трёх один.

А что со статьями вне серий? У них тот же кикер, только вместо «часть N из M» — «разбор», а панель слева наполняется из поля related во front matter: три-пять ссылок на близкие гайды. Серия — не обязанность, а опция.

Теперь ты можешь собрать серию из любых гайдов, сложив их в одну папку, — и переставлять части, меняя один weight, а не N статей.

#Что дальше

Мост внизу уже посчитал, что осталась одна часть. В ней — про цвет: почему все семь палитр этой страницы живут в data-файлах и как добавить свою, не тронув ни строчки темы.

Наивная модель такая: я пишу текст, и в одном месте мне нужна интерактивная иллюстрация. Кнопка, счётчик, что угодно. Кажется, дел на десять строк JS.

Теперь боль. В обычной теме эти десять строк некуда положить. Скрипт надо подключить в <head> — значит, править шаблон. Шаблон общий — значит, скрипт поедет на все страницы сразу. Чтобы не поехал, нужен реестр «какой скрипт какой странице» — значит, конфиг. Через месяц у тебя три статьи с виджетами и одна страница шаблона, которую страшно трогать. Текст живёт в одном месте, его код — в трёх других, и перенести статью целиком уже нельзя: она вросла в тему корнями.

#Статья — это папка

Здесь статья — это leaf bundle: папка, в которой лежит всё её хозяйство. Вот лента файлов бандла — той самой папки, из которой собрана эта страница:

Обязателен только index.md. Всё остальное — опциональные соседи: положил widgets.js рядом — тема сама его найдёт, минифицирует, отфингерпринтит и подключит только на этой странице. Положил widgets.css — то же самое со стилями. Положил og.png — обложка для соцсетей берётся авторская вместо сгенерированной.

#Два касания

Полный цикл «добавить живую иллюстрацию» — два касания. Первое: в тексте ставишь шорткод с идентификатором и заданием. Второе: в widgets.js регистрируешь инициализатор с тем же идентификатором:

Taiga.widget("w-hello", function (root) {
  root.innerHTML = ""; // убираем статик-фолбэк
  // …кнопка, счётчик, бейдж — весь код в файле рядом
});

Ни шаблонов, ни <head>, ни реестров. У шорткода есть парная форма: внутрь кладётся статичный фолбэк, который живёт в точке монтирования, пока JS его не заменит, — а если JS выключен, остаётся насовсем. Страница без скриптов деградирует в осмысленный текст, а не в дыру.

Заметь, чего в примере выше нет: собственных стилей. Строительные классы — .w-row для строки контролов, .w-btn для кнопок, .w-num для крупной цифры, .w-cap для строки-вывода — лежат в CSS темы, и виджет выглядит родным, не привезя ни одного своего правила. widgets.css нужен только когда этого набора не хватает — и тогда он, как и всё остальное, просто кладётся в папку.

#Рантайм не даст упасть

Taiga.widget — это маленький рантайм в теме. Он ждёт DOM, находит точку монтирования по идентификатору и вызывает твой колбэк, обернув его в try/catch: упавший виджет напишет в консоль и не уронит соседей. А если точки монтирования нет — шорткод убрали из текста — инициализатор молча пропускается.

А теперь проверь всё это на живом экземпляре. Виджет ниже смонтирован тем самым рантаймом из того самого widgets.js, что лежит в папке этой статьи:

И последнее: механизм не привязан к гайдам. widgets.js подхватывается у любого бандла — страница с интерактивом здесь не отдельный тип со своим шаблоном, а обычная markdown-страница, рядом с которой лежит скрипт.

Теперь ты можешь добавить живую иллюстрацию в любой гайд, не открыв ни одного файла темы.

#Что дальше

Эта статья — часть серии, и слева от текста уже стоит панель с её оглавлением, а в кикере написано «часть 1 из 3». Руками это никто не набирал. Откуда тема всё знает — во второй части.