Англійською мовою для розробників статичних сайтів Hugo

Hugo — це статичний генератор сайтів, написаний мовою Go, відомий, перш за все, швидкістю побудови — тисячі сторінок компілюється значно менше ніж за секунду. Його словниковий запас відображає його розробку, спрямовану на зміст: « розділи змісту », « таксономії », « архетипи ». Якщо ви документуєте або підтримуєте сайт заснований на Hugo — зазвичай, це портал документації або сайт з великим вмістом — цей підручник надає вам англійську мову, щоб ви могли чітко обговорити це питання.

---

Організація контенту

** Content section ** — тека верхнього рівня під content/, яку Hugo розглядає як окремий тип вмісту, кожен з яких має свої шаблони і сторінки списку. “Публікації блогу знаходяться в розділі posts, а документація знаходиться в розділі docs — кожен з них має свій шаблон списку та структуру URL.”

** Front matter ** — блок метаданих (YAML, TOML або JSON) у верхній частині файла вмісту, який визначає заголовок, дату, мітки і будь- які нетипові поля.

“Ми використовуємо TOML для послідовності на всьому сайті — змішування форматів файлів лише ускладнює grep для певного поля.”

** Archetype ** — файл шаблону, який використовується для попереднього заповнення тексту переднього плану під час створення нового вмісту заданого типу за допомогою hugo new.

“Запуск hugo new posts/my-article.md витягує з архетипу posts, тому кожен новий пост починається з правого переднього поля матеріалу, яке вже є на місці.”

** Пакет сторінок ** — заснований на теках спосіб групування файла вмісту з його власними локальними ресурсами (зображеннями, іншими файлами), щоб вони пересувалися разом, а не розкидані по спільній теці ресурсів.

• “Ми перетворили прикладні дослідження на збірки сторінок — зображення кожної з них тепер знаходяться поруч з файлом markdown, а не в окремій теку активів верхнього рівня.” *

---

Taxonomies

Taxonomy

** Таксономія ** — це спосіб класифікації вмісту — мітки і категорії є вбудованими прикладами, але ви можете визначити власні таксономії (наприклад, « серії » або « рівень складності »).

“Ми додали нетипову таксономію difficulty, щоб читачі могли переглядати підручники за « початківцями », « середніми » або « досвідченими » безпосередньо з сайту.”

Term

term є певним значенням в таксономії — наприклад, «kubernetes» є терміном в таксономії «теги».

“Hugo автоматично створює сторінку списку для кожного терміна — відвідування /tags/kubernetes/ показує всі статті, які містять цей термін, без жодної роботи вручну.”

---

Шаблони і рендерування

** Порядок пошуку у макеті ** — система Hugo, заснована на правилах, яка визначає, який файл шаблону слід застосувати до певного елемента вмісту, на основі його розділу, типу і формату виводу.

• “Коли сторінка відтворювалася з неправильним розкладом, виправлення полягало у розумінні порядку пошуку Hugo — більш специфічний шаблон у теці розділів мав би мати пріоритет.” *

** Часткова ** — фрагмент шаблона, який можна використовувати знову і знову (наприклад, заголовок або компонент картки), включений з інших шаблонів, щоб уникнути дублювання.

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

** Shortcode ** — фрагмент, який можна викликати з самого вмісту markdown, для речей, які не можна виразити за допомогою звичайного markdown — вбудованих елементів, блоків підписів або нетипових блоків компонування.

“Автори використовують {{< callout >}} shortcode для додавання поля попередження в середині статті з відміткою, без написання сирого HTML.”

** Render hook ** — спосіб перезаписати, як Hugo відтворює певний елемент відображення (наприклад, посилання або зображення) на всьому сайті, не торкаючись окремих файлів вмісту.

• “Ми додали гачок відтворення для зображень, щоб кожне зображення на сайті автоматично отримувало атрибути для лінивого завантаження, без необхідності для авторів писати якийсь HTML.” *

---

Побудувати словник виконання

** Час збирання ** — час, який знадобиться Hugo для створення повного сайту; зазвичай, цей час вимірюється сотнями мілісекунд, навіть для великих сайтів, що є однією з головних причин, чому команди обирають саме цей метод.

“Наш сайт документації має понад 3000 сторінок і все ще створюється менше ніж за секунду — це головна причина, чому ми не відчували тиску перейти на щось інше.”

** Перезавантаження у реальному часі ** — Сервер розробки Hugo автоматично перебудовує і оновлює переглядач при зміні файлів, надаючи майже миттєву інформацію під час написання вмісту.

• “Перезавантаження у реальному часі означає, що автор може переглянути зміни у переглядачі майже відразу після збереження файла.” *

---

Багатомовні і вихідні формати

** i18n / багатомовний режим ** — вбудована підтримка Hugo для підтримки одного і того ж сайту декількома мовами, з перекладеним вмістом, впорядкованим за локаллю.

“Ми працюємо у справжньому багатомовному режимі, а не просто перекладаємо рядки — кожна мова має своє дерево вмісту, а Hugo створює повністю окрему структуру URL для кожної локалі.”

** Формат виводу ** — Hugo може відтворювати той самий вміст у форматах HTML, JSON, RSS або інших форматах з одного джерела вмісту, налаштованого для кожного розділу.

“Ми додали формат виводу JSON для наших документів, щоб окремий інструмент пошуку міг індексувати вміст без перегляду відтвореного HTML.”

---

Виступав за команду «Гігант»

Situation	Phrase
Justifying the choice for a large docs site	”With thousands of pages, build speed matters — Hugo rebuilds this entire site in under a second, so contributors get instant feedback.”
Explaining a taxonomy to a content author	”Assign the ‘difficulty’ term in the front matter, and Hugo automatically adds this article to the right browse-by-difficulty page.”
Describing a render hook change	”We didn’t touch any content files — the render hook change means every image site-wide now lazy-loads automatically.”
Discussing multilingual setup	”Each language has its own content tree, so a missing translation shows up as a genuinely missing file, not a partially translated page.”

Поширені помилки

• Названня ** часткового ** « компонентом » без пояснення, що він не має поведінки на стороні клієнта — це шаблон включення на стороні сервера, а не інтерактивний блок.
• Використання фрази « ми додали категорію », коли більш точним терміном може бути ** таксономія ** або ** термін **, залежно від того, чи маєте на увазі систему класифікації, чи певне значення у ній.
• Описуючи швидкість Hugo як «бо вона статична» — багато статичних генераторів сайтів набагато повільніші; швидкість Hugo конкретно походить від написання на Go з важким внутрішнім кешуванням.

Практичні вправи

1. Поясніть у двох реченнях різницю між таксономією і терміном.
2. Написати коротку записку для автора змісту, у якій буде пояснено, як використовувати архетип для створення нової статті з правим переднім планом.
3. Написати проект одного абзацу з обґрунтуванням вибору Hugo замість JavaScript- заснованого статичного генератора сайтів для 3000- сторінкового сайту документації.

Зв’язані ресурси

• Англійська для розробників Docusaurus
• Англійська для Eleventy (11ty) Developers
• Англійська для розробників Gatsby

Недоліки: Неможливість використовувати для передачі мовлення

Основний словниковий запас технічного письменника — особливо того, хто працює з Hugo — зосереджений на ясності, точності і реальних інструкціях. Однак для розробників, чия перша мова не є англійською, навігація цими нюансами може бути неймовірно складною. Це не просто про те, щоб знати * що * сказати; це про те, щоб ефективно передати це значення таким чином, що резонує з переважно англомовною командою. Це часто включає розуміння тонких відмінностей у фразуваннях, визнання потенційної неоднозначності і демонстрацію активного підходу до спілкування. Здається простим запит, наприклад, «виправити це», може нести значну вагу - це означає, що проблему потрібно вирішити, і отримувач може запитати * чому * це проблема. Аналогічно, надто багатослівні пояснення можуть відчувати себе патріотично, в той час як короткі відповіді можуть бути відкинутими. Ключ - це побудувати місток розуміння через ретельний вибір слів і продемонструвати готовність до співпраці.

Однією з критичних областей, які часто ігноруються, є використання умовної мови. Розробники часто використовують такі фрази, як «слід», «може» або «може», коли пропонують поліпшення або описують потенційні рішення. Хоча ці слова цілком прийнятні в англійській мові, вони можуть бути інтерпретовані по-різному не-рідними носіїв, які можуть сприймати їх як надмірне хеджування їх ставок, що означає невизначеність, де очікується впевненість. І навпаки, заява про щось остаточно - “Це * має * бути виправлено” - може відчуватися вимогливим і потенційно конфронтаційним без чіткого пояснення роздумів за невідкладністю. Навчання балансувати прямоту з дипломатією є обов’язковим. Крім того, важливо розуміти різницю між «вадою» і «проблемою»; «вадою», як правило, має трохи більш негативну конотацію, ніж «проблемою», яку можна розглядати як щось, що потребує уваги, а не як притаманну помилку.

Поширений сценарій виникає під час перегляду коду. Уявіть, що ви отримали такий коментар щодо запиту на збирання: « Потрібно трохи попрацювати ». Хоча це виглядає безневинно, але це надзвичайно нечітке повідомлення. Кращий підхід буде таким: «Я помітив, що функція calculate_tax не обробляє крайові випадки для ставок ПДВ вище 20%. Чи можете ви додати перевірку цього?» Цей пункт надає контекст, визначає конкретну проблему і надає чіткий наказ розробнику, яким він повинен слідувати. Не менш важливо визнати своє власне розуміння — «Я не зовсім впевнений в цій інтеграції, але…» — демонструючи відкритість до зворотнього зв’язку і співпраці. Це про те, щоб представити себе як частину команди, готову навчатися і ефективно робити свій внесок.

# Example: Using Hugo's `dump` command for generating documentation
hugo static -d docs --start-collections "my_project" --no-color

Ця команда демонструє використання команди dump в екосистемі Hugo - сценарій, де точне формулювання про збір даних і вивід є життєво важливим. Нерідний мовець отримає користь від розуміння того, що « no- color » запобігає занадто великому заповненню терміналу, а « start- collections » вказує, які частини документації проекту включено до створених статичних файлів.