руководство · основы · часть 2 из 3

Написать первый гайд

проверено на v0.0.1 ~5 мин 554 слова

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

Содержание

Каркас одной командой
Front matter: что заполнять
Шорткоды
Виджет за два касания
Что дальше

#Каркас одной командой

создать каркас гайда

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

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

Ловушка

Путь в команде — без /index.md. Напишешь guides/my-first/index.md — Hugo переключится в режим одиночного файла и молча не скопирует соседние файлы архетипа. Папка без widgets.js — первый признак этой ошибки.

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

index.md — 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:

касание 1 — шорткод в тексте

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

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

касание 2 — 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, собственные разделы и второй язык.