Cтиль документації

• 1: Посібник з вмісту документації
• 2: Посібник зі стилю документації
• 3: Створення діаграм
• 4: Написання нової теми
• 5: Типи контенту сторінок
• 6: Організація контенту
• 7: Власні shortcodes Hugo

1 - Посібник з вмісту документації

Ця сторінка містить вказівки щодо документації Kubernetes.

Якщо у вас є запитання про те, що дозволено, приєднуйтесь до каналу #sig-docs у Kubernetes Slack і запитуйте!

Ви можете зареєструватися на Kubernetes Slack за адресою https://slack.k8s.io/.

Для отримання інформації про створення нового вмісту для документації Kubernetes, дотримуйтесь посібника зі стилю.

Огляд

Сирці вебсайту Kubernetes, включаючи документацію, знаходиться в репозиторії kubernetes/website.

Більшість документації Kubernetes знаходиться в теці kubernetes/website/content/<language_code>/docs і специфічна для проєкту Kubernetes.

Що дозволено

Документація Kubernetes дозволяє вміст зі сторонніх проєктів тільки тоді, коли:

• Вміст документує програмне забезпечення в проєкті Kubernetes
• Вміст документує програмне забезпечення, яке знаходиться поза проєктом, але необхідне для функціонування Kubernetes
• Вміст є канонічним на kubernetes.io або посилається на канонічний вміст в іншому місці

Сторонній вміст

Документація Kubernetes включає приклади застосування проєктів у проєкті Kubernetes — проєктів, що знаходяться в організаціях GitHub kubernetes та kubernetes-sigs.

Посилання на активний вміст у проєкті Kubernetes завжди дозволені.

Для функціонування Kubernetes необхідний деякий сторонній вміст. Прикладами є контейнерні середовища (containerd, CRI-O, Docker), мережева політика (втулки CNI), контролери Ingress, та логування.

Документація може посилатися на стороннє програмне забезпечення з відкритим вихідним кодом (OSS) поза проєктом Kubernetes тільки якщо воно необхідне для функціонування Kubernetes.

Контент з подвійним джерелом

Коли це можливо, документація Kubernetes посилається на канонічні джерела замість розміщення дублікату вмісту.

Контент з подвійним джерелом вимагає вдвічі більше зусиль (або більше!) для підтримки та швидше стає застарілим.

Додаткова інформація

Якщо у вас є запитання про дозволений вміст, приєднуйтесь до каналу #sig-docs у Kubernetes Slack і запитуйте!

Що далі

• Ознайомтесь з посібником зі стилю.

2 - Посібник зі стилю документації

Ця сторінка надає вказівки щодо стилю написання документації Kubernetes. Це вказівки, а не правила. Використовуйте здоровий глузд та не соромтеся пропонувати зміни до цього документа за допомогою pull request.

Для отримання додаткової інформації про створення нового вмісту для документації Kubernetes, прочитайте Посібник з вмісту документації.

Зміни до посібника зі стилю вносяться групою SIG Docs. Щоб запропонувати зміну або доповнення, додайте її до порядку денного на наступну зустріч SIG Docs та відвідайте зустріч, щоб взяти участь в обговоренні.

Мова

Документація Kubernetes була перекладена кількома мовами (див. локалізовані файли README).

Процес локалізації документації для інших мови описано в розділіЛокалізація документації Kubernetes.

Документація англійською мовою використовує правопис та граматику американської англійської.

Стандарти форматування документації

Використовуйте UpperCamelCase для обʼєктів API

Коли ви посилаєтеся на взаємодію з обʼєктом API, використовуйте UpperCamelCase, також відомий як Pascal case. Ви можете зустріти інші варіанти написання, наприклад, "configMap", в Довіднику API. У загальній документації краще використовувати UpperCamelCase, називаючи обʼєкт "ConfigMap".

Коли ви загалом обговорюєте обʼєкт API, використовуйте велику літеру тільки на початку речення.

Наведені нижче приклади зосереджуються на капіталізації. Для отримання додаткової інформації про форматування імен обʼєктів API перегляньте відповідні рекомендації щодо Стилю коду.

Використовуйте кутові дужки для заповнювачів

Використовуйте кутові дужки для заповнювачів. Поясніть читачеві, що представляє заповнювач, наприклад:

Показ інформацію про Pod:

kubectl describe pod <pod-name> -n <namespace>

Якщо простір імен Podʼа є default, ви можете пропустити параметр -n.

Використовуйте жирний шрифт для елементів інтерфейсу користувача

Використовуйте курсив для визначення або введення нових термінів

Використовуйте стиль коду для імен файлів, тек та шляхів

Використовуйте міжнародний стандарт для пунктуації всередині лапок

Форматування вбудованого коду

Використовуйте кодовий стиль для вбудованого коду та команд

Для вбудованого в документі HTML коду використовуйте теґ <code>. У документі Markdown використовуйте зворотну лапку (`). Проте, API обʼєкти, такі як StatefulSet або ConfigMap, пишуться дослівно (без зворотних лапок); це дозволяє використовувати апострофи для позначення присвійного відмінка.

Використовуйте стиль коду для імен полів обʼєктів та просторів імен

Використовуйте стиль коду для назв команд, інструментів та компонентів Kubernetes

Початок речення з назви інструменту або компонента

Використовуйте загальний дескриптор замість назви компонента

Використовуйте звичайний стиль для значень полів типу string та integer

Для значень полів типу string або integer використовуйте звичайний стиль без лапок.

Однак, розгляньте можливість цитування значень у випадках, коли є ризик, що читачі можуть сплутати значення з типом API.

Посилання на API ресурси Kubernetes

Цей розділ описує, як ми посилаємося на API ресурси в документації.

Уточнення щодо терміна "ресурс"

Kubernetes використовує слово ресурс для позначення ресурсів API. Наприклад, шлях URL /apis/apps/v1/namespaces/default/deployments/my-app представляє Deployment з назвою "my-app" у просторі імен "default". У термінології HTTP, простір імен є ресурсом — так само як всі веб-URL ідентифікують ресурс.

Документація Kubernetes також використовує "ресурс" для опису запитів і обмежень на використання процесорів і памʼяті. Дуже часто доцільно посилатися на API ресурси як на "API ресурси", щоб уникнути плутанини з процесорними ресурсами та ресурсами памʼяті або з іншими видами ресурсів.

Якщо ви використовуєте назву ресурсу в нижньому регістрі у множині, наприклад, deployments або configmaps, надайте додатковий контекст, щоб допомогти читачам зрозуміти, що ви маєте на увазі. Якщо ви використовуєте цей термін у контексті, де також можна використовувати назву в UpperCamelCase, і є ризик неоднозначності, розгляньте можливість використання типу API в UpperCamelCase.

Коли використовувати терміни Kubernetes API

Різні терміни Kubernetes API включають:

• API типи (kind): назви, які використовуються в URL API (такі як pods, namespaces). API типи іноді також називають типами ресурсів.
• API ресурс: одиничні екземпляри API типу (такі як pod, secret).
• Обʼєкт: ресурс, який служить як "запис наміру". Обʼєкт є бажаним станом для конкретної частини вашого кластера, який намагається підтримувати панель управління Kubernetes. Всі обʼєкти в API Kubernetes також є ресурсами.

Для ясності ви можете додати "ресурс" або "обʼєкт", коли посилаєтесь на API ресурс у документації Kubernetes. Наприклад: пишіть "обʼєкт Secret", замість "Secret". Якщо з контексту зрозуміло, що мова йде про ресурс, можна не додавати це слово.

Розгляньте можливість перефразування, коли це допомагає уникнути непорозумінь. Звичайною ситуацією є випадок, коли ви хочете почати речення з API типу, наприклад, "Secret"; оскільки в англійській та інших мовах заголовні літери використовуються на початку речень, читачі не можуть визначити, чи маєте ви на увазі API тип або загальне поняття. Перефразування може допомогти.

Назви API ресурсів

Завжди форматуйте назви API ресурсів, використовуючи UpperCamelCase, також відомий як PascalCase. Не пишіть API типи з використанням форматування коду.

Не розбивайте назву API обʼєкта на окремі слова. Наприклад, використовуйте PodTemplateList, а не Pod Template List.

Для отримання додаткової інформації про PascalCase і форматування коду, ознайомтесь із відповідними рекомендаціями щодо Використання UpperCamelCase для API обʼєктів та Використання кодового стилю для вбудованого коду, команд і API обʼєктів.

Для отримання додаткової інформації про термінологію Kubernetes API, ознайомтесь із відповідними рекомендаціями щодо Термінології API Kubernetes.

Форматування фрагментів коду

Не включайте символ командного рядка

Відокремлюйте команди від їх виводу

Переконайтеся, що Pod працює на обраному вами вузлі:

kubectl get pods --output=wide

Результат буде схожим на цей:

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Версіювання прикладів для Kubernetes

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

Якщо інформація є специфічною для версії, версія Kubernetes повинна бути визначена у розділі prerequisites шаблону Task або шаблону Tutorial. Після збереження сторінки, розділ prerequisites буде показаний з назвою — Перед тим, як почати.

Щоб вказати версію Kubernetes для сторінки з завданням або навчальним посібником, включіть min-kubernetes-server-version у front matter сторінки.

Якщо YAML приклад знаходиться у файлі окремо, знайдіть та перегляньте теми, які включають його як посилання. Переконайтеся, що будь-які теми, які використовують окремий YAML, мають відповідну інформацію про версії. Якщо окремий YAML файл не посилається на жодні теми, розгляньте можливість його видалення замість оновлення.

Наприклад, якщо ви пишете навчальний посібник, що стосується версії Kubernetes 1.8, front matter вашого markdown файлу мають виглядати приблизно так:

---
title: <ваша назва навчального посібника>
min-kubernetes-server-version: v1.8
---

У прикладах коду та конфігурацій не включайте коментарі про альтернативні версії. Будьте обережні, щоб не включати некоректні твердження у ваші приклади у вигляді коментарів, наприклад:

apiVersion: v1 # попередні версії використовують...
kind: Pod
...

Словник Kubernetes.io

Список специфічних для Kubernetes термінів і слів, які слід використовувати послідовно у всьому сайті.

Shortcodes

Hugo Shortcodes допомагають створювати різні рівні риторичної привабливості. Наша документація підтримує три різні Shortcodes в цій категорії: Note {{< note >}}, Caution {{< caution >}} і Warning {{< warning >}}.

1. Оточуйте текст відкриваючим та закриваючим Shortcodeʼом.

2. Використовуйте наступний синтаксис для застосування стилю:

   {{< note >}}
   Немає необхідності включати префікс; Shortcode автоматично додає його. (Note:, Caution:, тощо)
   {{< /note >}}
   

   Вихідний результат:

   Примітка:

   Обраний префікс збігається з текстом теґа.

Note

Використовуйте {{< note >}} для виділення поради або корисної інформації.

Наприклад:

{{< note >}}
Ви _все ще_ можете використовувати Markdown всередині цих Shortcodeʼів.
{{< /note >}}

Вихідний результат:

Ви можете використовувати {{< note >}} у списку:

1. Використовуйте Shortcode примітки у списку

1. Другий пункт з вбудованою приміткою

   {{< note >}}
   Shortcode Warning, Caution і Note, вбудовані у списки, повинні мати відповідний відступ (на рівні початку тексту списку). Див. [Поширені проблеми з Shortcode](#common-shortcode-issues).
   {{< /note >}}

1. Третій пункт у списку

1. Четвертий пункт у списку

Вихідний результат:

1. Використовуйте Shortcode примітки у списку

2. Другий пункт з вбудованою приміткою

   Примітка:

   Шорткоди Warning, Caution і Note, вбудовані у списки, повинні мати відповідний відступ (на рівні початку тексту списку). Див. Поширені проблеми з Shortcode.

3. Третій пункт у списку

4. Четвертий пункт у списку

Caution

Використовуйте {{< caution >}} для привернення уваги до важливої інформації, щоб уникнути помилок.

Наприклад:

{{< caution >}}
Стиль виклику застосовується лише до рядка теґа вище безпосередньо.
{{< /caution >}}

Вихідний результат:

Warning

Використовуйте {{< warning >}} для вказівки на небезпеку або важливу інформацію, яку потрібно обовʼязково враховувати.

Наприклад:

{{< warning >}}
Будьте обережні.
{{< /warning >}}

Вихідний результат:

Поширені проблеми з Shortcode

Нумеровані списки

Shortcode переривають нумеровані списки, якщо не зробити відступ у на рівні початку тексту списку перед сповіщенням та теґом.

Наприклад:

1. Розігрійте духовку до 350˚F

1. Приготуйте тісто та вилийте його у форму.
   {{< note >}}Змастіть форму для кращих результатів.{{< /note >}}

1. Випікайте 20-25 хвилин або до готовності.

Вихідний результат:

1. Розігрійте духовку до 350˚F

2. Приготуйте тісто та вилийте його у форму.

   Примітка:

   Змастіть форму для кращих результатів.

3. Випікайте 20-25 хвилин або до готовності.

Вирази Include

Shortcode всередині include statements зламають збірку. Необхідно вставити їх у батьківський документ до і після виклику include. Наприклад:

{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}

Елементи Markdown

Переноси рядків

Використовуйте один символ переносу рядка (\n) для розділення контенту на рівні блоків, таких як заголовки, списки, зображення, блоки коду тощо. Винятком є заголовки другого рівня, де необхідно зробити два переноси рядка. Заголовки другого рівня слідують після заголовків першого рівня (або заголовка) без передуючих абзаців або тексту. Два переноси рядка допомагають краще візуалізувати загальну структуру контенту в текстовому редакторі.

Ручне перенесення абзаців у вихідному коді Markdown є доречним, оскільки інструмент git та сайт GitHub генерують порівняння файлів на основі рядків. Ручне перенесення довгих рядків допомагає рецензентам легко знаходити зміни у PR і надавати зворотний звʼязок. Це також допомагає командам, які займаються локалізацією, відслідковувати зміни на рівні рядків¹. Перенесення рядка може відбуватися в кінці речення або після знака пунктуації. Винятком є випадки, коли Markdown-посилання або шорткод очікується в одному рядку.

Заголовки та назви

Користувачі цієї документації можуть використовувати інструменти озвучування тексту (екранний зчитувач) або іншу допоміжну технологію (AT). Екранні зчитувачі є лінійними вихідними пристроями, що виводять елементи на сторінку по одному. Якщо на сторінці багато контенту, ви можете використовувати заголовки для створення внутрішньої структури сторінки. Гарна структура сторінки допомагає всім користувачам легко орієнтуватися на сторінці або фільтрувати теми, які їх цікавлять.

Абзаци

Посилання

Списки

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

• Закінчуйте кожен елемент у списку крапкою, якщо один або більше елементів у списку є завершеними реченнями. Для збереження послідовності зазвичай всі елементи або жоден з них мають бути завершеними реченнями.

  Примітка:

  Упорядковані списки, що є частиною незавершеного вступного речення, можуть бути написані з маленької літери і пунктуацією так, ніби кожен елемент є частиною вступного речення.

• Використовуйте цифру один з крапкою (1.) для упорядкованих списків.

• Використовуйте (+), (*), або (-) для неупорядкованих списків, але якийсь один з цих символів у одному тексті (уникайте їх змішування)

• Залишайте порожній рядок після кожного списку.

• Відступайте вкладені списки на відповідну кількість пробілів, так щоб сімвол початку елемента спіску був на рівні з початком тексту елемента вищого рівня (наприклад, ⋅⋅⋅).

• Елементи списку можуть складатися з кількох абзаців. Кожен наступний абзац у пункті списку повинен бути відступлений нарівень початку тексту елементу списку або один табулятор.

Таблиці

Семантична мета таблиці — це представлення табличних даних. Користувачі з гарним зором можуть швидко сканувати таблицю, але екранний зчитувач проходить її рядок за рядком. Підпис таблиці використовується для створення описового заголовка для таблиці даних. Допоміжні технології (AT) використовують елемент підпису HTML для таблиці, щоб ідентифікувати вміст таблиці користувачеві в межах структури сторінки.

• Додавайте підписи до таблиць за допомогою shortcodes Hugo для таблиць.

Рекомендації щодо створення контенту

Цей розділ містить рекомендації для створення чіткого, лаконічного і послідовного контенту.

Використовуйте теперішній час

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

Використовуйте активний стан

Виняток: Використовуйте пасивний стан, якщо активний стан призводить до незручної конструкції.

Використовуйте просту і пряму мову

Використовуйте просту і пряму мову. Уникайте використання зайвих фраз, наприклад, слова "будь ласка".

Звертайтесь до читача на "ви"

Уникайте латинських фраз

Віддавайте перевагу англійським (місцевим) термінам замість латинських абревіатур.

Виняток: Використовуйте "etc." (et cetera) для позначення "та інше".

Шаблони, яких слід уникати

Уникайте використання "ми"

Використання "ми" у реченні може бути заплутаним, оскільки читач може не знати, чи є він частиною "ми", про яке ви говорите.

Уникайте жаргону та ідіом

Для багатьох читачів англійська є другою мовою. Уникайте жаргону та ідіом, щоб допомогти їм краще зрозуміти тему.

Уникайте тверджень про майбутнє

Уникайте обіцянок або натяків на майбутнє. Якщо вам потрібно говорити про функцію в альфа-версії, розмістіть текст під заголовком, який позначає його як альфа-інформацію.

Винятком з цього правила є документація про оголошені застарівання функцій, які плануються до видалення в майбутніх версіях. Один з прикладів такої документації — Посібник з міграції із застарілих API.

Уникайте тверджень, які незабаром стануть неактуальними

Уникайте слів таких як "зараз" і "новий". Функція, яка є новою сьогодні, може не вважатися новою через кілька місяців.

Уникайте слів, що припускають певний рівень розуміння

Уникайте слів таких як "просто", "легко", "зрозуміло". Ці слова не додають цінності.

Файл EditorConfig

Проєкт Kubernetes підтримує файл EditorConfig, який встановлює загальні стилістичні уподобання в текстових редакторах, таких як VS Code. Ви можете використовувати цей файл, якщо хочете переконатися, що ваші внески відповідають решті проєкту. Щоб переглянути файл, зверніться до .editorconfig в кореневій теці репозиторію.

Що далі

• Дізнайтеся про написання нової теми.
• Дізнайтеся про використання шаблонів сторінок.
• Дізнайтеся про власні hugo shortcodes.
• Дізнайтеся про створення pull request.

3 - Створення діаграм

Цей посібник показує, як створювати, редагувати та поширювати діаграмами за допомогою JavaScript бібліотеки Mermaid. Mermaid.js дозволяє створювати діаграми за допомогою простого синтаксису, подібного до Markdown, всередині Markdown-файлів. Ви також можете використовувати Mermaid для створення файлів зображень у форматі .svg або .png, які ви можете додати до документації.

Цільовою аудиторією цього посібника є будь-хто, хто бажає дізнатися про Mermaid та/або як створювати і додавати діаграми до документації Kubernetes.

На схемі 1 показані теми, які розглядаються в цьому розділі.

Схема 1. Теми, які розглядаються в цьому розділі

Все що вам треба для роботи з Mermaid це:

• Знання основ markdown.
• Користуватись онлайн редактором Mermaid.
• Користуватись Hugo shortcodes.
• Користуватись Hugo shortcode {{< figure >}}.
• Виконувати локальний перегляд в Hugo.
• Знати як брати участь у створенні нового контенту.

Чому слід використовувати діаграми в документації

Діаграми покращують ясність та сприйняття документації. Це має переваги як для користувачів, так і для контриб'юторів.

Переваги для користувачів включають:

• Приємне перше враження. Детальна текстова сторінка привітання може налякати користувачів, особливо новачків у Kubernetes.
• Швидке освоєння концепцій. Діаграма може допомогти користувачам зрозуміти ключові моменти складної теми. Ваша діаграма може слугувати візуальним навчальним посібником для занурення в деталі теми.
• Краще запамʼятовування. Для деяких легше запамʼятати зображення, ніж текст.

Переваги для учасників включають:

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

Вам слід враховувати вашу цільову аудиторію. Окрім досвідчених користувачів K8s, у вас буде багато новачків у Kubernetes. Навіть проста діаграма може допомогти новим користувачам засвоїти концепції Kubernetes. Вони стають впевненішими та більш схильними до подальшого дослідження Kubernetes та документації.

Mermaid

Mermaid — це бібліотека JavaScript з відкритим вихідним кодом, яка дозволяє створювати, редагувати та легко ділитися діаграмами, використовуючи простий синтаксис, схожий на Markdown, який використовується в файлах Markdown.

Нижче наведено особливості Mermaid:

• Простий синтаксис коду.
• Включає вебінструмент для кодування та перегляду ваших діаграм.
• Підтримує кілька форматів, включаючи діаграми процесів, станів та послідовностей.
• Легке співробітництво з колегами через URL-адресу для кожної діаграми.
• Широкий вибір форм, ліній, тем та стилів.

Переваги використання Mermaid:

• Немає потреби в спеціальних інструментах для створення діаграм.
• Відповідає поточному робочому процесу з використанням PR. Ви можете розглядати код Mermaid як просто текст Markdown, доданий у ваш PR.
• Простий інструмент створює прості діаграми. Не хочете витрачати час на створення надто складних і деталізованих зображень. Тримайте їх простими!

Mermaid надає простий, відкритий та прозорий метод для спільнот SIG для додавання, редагування та співпраці над діаграмами для нової чи наявної документації.

Онлайн редактор

Онлайн редактор Mermaid — це вебінструмент, який дозволяє створювати, редагувати та переглядати діаграми.

Нижче наведено функції редактора:

• Показує код Mermaid разом зі згенерованою діаграмою.
• Генерує URL для кожної збереженої діаграми. URL відображається в адресному рядку вашого оглядача. Ви можете поділитися URL з колегами, які можуть отримати доступ до діаграми та змінювати її.
• Можливість отримати файли .svg або .png.

Методи створення діаграм

На схемі 2 показано три способи створення та додавання діаграм.

Схема 2. Методи створення діаграм.

В тексті

На схемі 3 показано кроки для додавання діаграми за допомогою методу Inline.

Схема 3. Кроки метода inline

Ось перелік кроків, які слід виконати для додавання діаграми за допомогою методу Inline:

1. Створіть вашу діаграму за допомогою онлайн редактора.
2. Збережіть URL діаграми для подальшого доступу.
3. Скопіюйте код Mermaid у місце в вашому файлі .md туди, де ви хочете, щоб зʼявилася діаграма.
4. Додайте підпис під діаграмою, використовуючи текст Markdown.

Під час побудови Hugo виконується код Mermaid і перетворюється на діаграму.

Ось приклад фрагмента коду, що міститься у файлі .md:

---
title: My PR
---
Figure 17 shows a simple A to B process.
some markdown text
...
{{< mermaid >}} 
    graph TB
    A --> B
{{< /mermaid >}}

Figure 17. A to B
more text

Для отримання додаткової інформації про підписи до діаграм, дивіться Як використовувати підписи.

Нижче наведено переваги методу Inline:

• Використання онлайн редактора.
• Легко копіювати код Mermaid до та з онлайн редактора та вашого файлу .md.
• Відсутність необхідності окремої обробки файлів зображень .svg.
• Текст контенту, код діаграми та підпис до діаграми знаходяться в одному файлі .md.

Ви повинні використовувати локальний та Netlify попередній перегляд для перевірки правильного показу діаграми.

Mermaid+SVG

На схемі 4 показано кроки для додавання діаграми за допомогою методу Mermaid+SVG.

Схема 4. Кроки методу Mermaid+SVG

Нижче наведено кроки, які слід виконати для додавання діаграми за допомогою методу Mermaid+SVG:

1. Створіть діаграму за допомогою онлайн редактора.
2. Збережіть URL діаграми для подальшого доступу.
3. Згенеруйте файл зображення .svg для діаграми та завантажте його до відповідної теки images/.
4. Використовуйте shortcode {{< figure >}} для посилання на діаграму у файлі .md.
5. Додайте підпис за допомогою параметра caption у shortcode {{< figure >}}.

Наприклад, використовуйте онлайн редактор для створення діаграми з назвою boxnet. Збережіть URL діаграми для подальшого доступу. Згенеруйте та завантажте файл boxnet.svg до відповідної теки ../images/.

Використовуйте shortcode {{< figure >}} у файлі .md вашого PR, щоб посилатися на файл зображення .svg та додати підпис.

{{< figure src="/static/images/boxnet.svg" alt="Boxnet figure" class="diagram-large" caption="Figure 14. Boxnet caption" >}}

Для отримання додаткової інформації про підписи до діаграм дивіться Як використовувати підписи.

Ви повинні додати URL онлйн редактора як коментар у файлі зображення .svg, використовуючи текстовий редактор. Наприклад, ви б включили наступне на початку файлу зображення .svg:

<!-- Щоб переглянути або редагувати код Mermaid, використовуйте наступний URL: -->
<!-- https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb ... <продовження рядка URL> -->

Нижче наведено переваги методу Mermaid+SVG:

• Використання інструменту онлайн редактора.
• Інструмент онлайн редактора підтримує найсучасніший набір функцій Mermaid.
• Використання існуючих методів kubernetes/website для обробки файлів зображень .svg.
• Середовище не вимагає підтримки Mermaid.

Переконайтеся, що ваша діаграма правильно відображається, використовуючи локальний та Netlify попередній перегляд.

Зовнішні інструменти

На схемі 5 показано кроки, яких слід дотримуватися для додавання діаграми за допомогою зовнішнього інструменту.

Спочатку створіть діаграму за допомогою зовнішнього інструменту і збережіть її як файл зображення у форматі .svg або .png. Після цього виконайте ті самі кроки, що й у методі Mermaid+SVG для додавання файлів зображень у форматі .svg.

Схема 5. Кроки методу з використання зовнішнього інструменту

Нижче наведено кроки, які слід виконати для додавання діаграми за допомогою методу External Tool:

1. Використовуйте зовнішній інструмент для створення діаграми.
2. Збережіть координати діаграми для доступу інших учасників. Наприклад, ваш інструмент може надати посилання на зображення діаграми, або ви можете зберегти файл з вихідним кодом, такий як .xml, у публічному репозиторії для подальшого доступу інших учасників.
3. Згенеруйте та збережіть діаграму у вигляді файлу зображення .svg або .png. Завантажте цей файл у відповідну теку ../images/.
4. Використовуйте shortcode {{< figure >}} для посилання на діаграму у файлі .md.
5. Додайте підпис за допомогою параметра caption у shortcode {{< figure >}}.

Ось приклад використання shortcode {{< figure >}} для діаграми images/apple.svg:

{{< figure src="/static/images/apple.svg" alt="red-apple-figure" class="diagram-large" caption="Figure 9. A Big Red Apple" >}}

Якщо ваш зовнішній інструмент малювання дозволяє:

• Ви можете включати кілька логотипів .svg або .png, іконок та зображень у свою діаграму. Однак, переконайтеся, що ви дотримуєтеся авторських прав і дотримуєтесь керівництва Kubernetes щодо використання контенту третіх сторін.
• Ви повинні зберегти координати діаграми для подальшого доступу інших учасників. Наприклад, ваш інструмент може надати посилання на зображення діаграми, або ви можете зберегти файл з вихідним кодом, наприклад .xml, для доступу інших учасників.

Для отримання додаткової інформації про логотипи та зображення K8s і CNCF, зверніться до розділу CNCF Artwork.

Нижче наведено переваги методу External Tool:

• Учасники добре знайомі з зовнішнім інструментом.
• Діаграми потребують більше деталей, ніж може надати Mermaid.

Не забудьте перевірити, чи правильно відображається ваша діаграма, використовуючи локальний та Netlify попередній перегляд.

Приклади

У цьому розділі показано декілька прикладів діаграм Mermaid.

Приклад 1 — Обмеження на поширення топології Podʼів

Схема 6 показує діаграму зі сторінки Обмеження на поширення топології Podʼів

Схема 6. Обмеження поширення топології Podʼів

Код:

graph TB
   subgraph "zoneB"
       n3(Node3)
       n4(Node4)
   end
   subgraph "zoneA"
       n1(Node1)
       n2(Node2)
   end
 
   classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000;
   classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff;
   classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5;
   class n1,n2,n3,n4 k8s;
   class zoneA,zoneB cluster;

Приклад 2 – Ingress

Схема 7 показує діаграму, що зʼявляється на сторінці Що таке Ingress.

Code block:

graph LR;
 client([client])-. Ingress-managed <br> load balancer .->ingress[Ingress];
 ingress-->|routing rule|service[Service];
 subgraph cluster
 ingress;
 service-->pod1[Pod];
 service-->pod2[Pod];
 end
 classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000;
 classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff;
 classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5;
 class ingress,service,pod1,pod2 k8s;
 class client plain;
 class cluster cluster;

Приклад 3 — Потік системи К8s

На схемі 8 зображено Mermaid-діаграму послідовності, яка показує системний потік між компонентами K8 для запуску контейнера.

Код:

%%{init:{"theme":"neutral"}}%%
sequenceDiagram
    actor me
    participant apiSrv as control plane<br><br>api-server
    participant etcd as control plane<br><br>etcd datastore
    participant cntrlMgr as control plane<br><br>controller<br>manager
    participant sched as control plane<br><br>scheduler
    participant kubelet as node<br><br>kubelet
    participant container as node<br><br>container<br>runtime
    me->>apiSrv: 1. kubectl create -f pod.yaml
    apiSrv-->>etcd: 2. save new state
    cntrlMgr->>apiSrv: 3. check for changes
    sched->>apiSrv: 4. watch for unassigned pods(s)
    apiSrv->>sched: 5. notify about pod w nodename=" "
    sched->>apiSrv: 6. assign pod to node
    apiSrv-->>etcd: 7. save new state
    kubelet->>apiSrv: 8. look for newly assigned pod(s)
    apiSrv->>kubelet: 9. bind pod to node
    kubelet->>container: 10. start container
    kubelet->>apiSrv: 11. update pod status
    apiSrv-->>etcd: 12. save new state

Ви можете стилізувати один або декілька елементів діаграми за допомогою CSS. Це досягається за допомогою двох типів операторів у коді Mermaid.

• classDef визначає клас атрибутів стилю.
• class визначає один або декілька елементів, до яких буде застосовано клас.

В коді до схеми 7 ви можете побачити приклад.

classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff; // визначає стиль для класу k8s
class ingress,service,pod1,pod2 k8s; // Клас k8s застосовується до елементів ingress, service, pod1 та pod2.

Ви можете включити один або декілька операторів classDef та class у вашу діаграму. Ви також можете використовувати офіційний шістнадцятковий код кольору K8s #326ce5 для компонентів K8s у вашій діаграмі.

Для отримання додаткової інформації про стилізацію та класи див. Mermaid Styling and classes docs.

Як використовувати підписи до діаграм

Підпис — це короткий опис діаграми. Підпис може містити назву або короткий опис діаграми. Підписи не замінюють пояснювальний текст у вашій документації, а радше слугують як "контекстний звʼязок" між цим текстом та вашою діаграмою.

Поєднання тексту та діаграми, повʼязаних разом за допомогою підпису, допомагає надати чітке уявлення про інформацію, яку ви хочете донести до користувача.

Без підписів ви змушуєте користувача шукати текст над або під діаграмою, щоб зрозуміти її значення. Це може викликати невдоволення користувача.

На схемі 9 показано три компоненти правильного використання підписів: діаграма, підпис до діаграми та посилання на діаграму в тексті.

Схема 9. Компоненти заголовків

Діаграма

Методи Mermaid+SVG та External Tool генерують файли зображень у форматі .svg.

Існує shortcode {{< figure >}} для діаграми, що знаходиться у файлі зображення .svg, збереженому в /images/docs/components-of-kubernetes.svg:

{{< figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Схема 4. Компоненти архітектури Kubernetes" >}}

Ви повинні передавати значення src, alt, class та caption у shortcode {{< figure >}}. Ви можете змінювати розмір діаграми, використовуючи класи diagram-large, diagram-medium та diagram-small.

Дивіться Методи створення діаграм для отримання додаткової інформації про різні методи створення діаграм.

Підпис до діаграми

Далі додайте підпис до діаграми.

Якщо ви використовуєте діаграму з файла зображення .svg, вам слід використовувати параметр caption shortcodeʼа {{< figure >}}.

{{< figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Схема 4. Компоненти архітектури Kubernetes" >}}

Якщо ви використовуєте діаграму, що є вбудованим кодом Mermaid, тоді слід використовувати текст Markdown.

Схема 4. Компоненти архітектури Kubernetes

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

• Використовуйте shortcode {{< figure >}} для додавання підпису до діаграм, створених за допомогою методів Mermaid+SVG та External Tool.
• Використовуйте простий текст Markdown для додавання підпису до діаграм, створених за допомогою методу Inline.
• Перед підписом діаграми додайте Схема НОМЕР.. Ви повинні використовувати слово Схема, і номер повинен бути унікальним для кожної діаграми на вашій сторінці документації. Додайте крапку після номера.
• Додайте текст підпису діаграми після Схема НОМЕР. в тому ж рядку. Підпис повинен закінчуватися крапкою. Зберігайте текст підпису коротким.
• Розташовуйте підпис до діаграми ПІД вашою діаграмою.

Посилання на діаграму

Нарешті, ви можете додати посилання на діаграму. Воно використовується у вашому тексті та повинно передувати самій діаграмі. Це дозволяє користувачеві повʼязати ваш текст із відповідною діаграмою. Схема НОМЕР у вашому посиланні та підписі повинні співпадати.

Вам слід уникати використання розпливчастих посилань, таких як ..зображення нижче.. або ..наступна схема..

Ось приклад посилання на діаграму:

Схема 10 зображує компоненти архітектури Kubernetes.
Панель управління ...

Посилання на діаграми є необовʼязковими, і є випадки, коли вони можуть бути невідповідними. Якщо ви не впевнені, додайте посилання на діаграму у ваш текст, щоб побачити, чи виглядає і звучить воно добре. Коли виникають сумніви, використовуйте посилання на діаграму.

Повна картина

Схема 10 показує діаграму архітектури Kubernetes, яка включає діаграму, підпис до діаграми та посилання на діаграму. Shortcode {{< figure >}} показує діаграму, додає підпис і включає необовʼязковий параметр link, щоб ви могли мати гіперпосилання на діаграму. Посилання на діаграму знаходиться в цьому абзаці.

Ось shortcode {{< figure >}} для цієї діаграми:

{{< figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Схема 10. Архітектура Kubernetes." link="/docs/concepts/overview/components/" >}}

Поради

• Завжди використовуйте оналйн редактор для створення/редагування вашої діаграми.

• Завжди використовуйте локальний Hugo та попередній перегляд Netlify, щоб перевірити, як діаграма відображається в документації.

• Включайте джерела діаграм, такі як URL, місцезнаходження вихідного коду або вказуйте, що код є самодокументуючим.

• Завжди використовуйте підписи до діаграм.

• Дуже корисно включати зображення діаграми у форматі .svg або .png та/або вихідний код Mermaid у тікетах та PRs.

• Для методів Mermaid+SVG та External Tool використовуйте файли зображень .svg, оскільки вони залишаються чіткими при збільшенні діаграми.

• Найкраща практика для файлів .svg — завантажити їх в інструмент для редагування SVG та використати функцію "Конвертувати текст у криві". Це гарантує, що діаграма відображатиметься однаково на всіх системах, незалежно від доступності шрифтів і підтримки рендерингу шрифтів.

• Mermaid не підтримує додаткові іконки або зображень.

• Shortcodes Hugo Mermaid не працюють в оналайн редакторі.

• Кожного разу, коли ви змінюєте діаграму в оналайн редакторі, ви повинні зберегти її, щоб згенерувати новий URL для діаграми.

• Натисніть на діаграми в цьому розділі, щоб переглянути код і відображення діаграми в оналайн редакторі.

• Перегляньте вихідний код цієї сторінки, diagram-guide.md, для отримання додаткових прикладів.

• Ознайомтеся з документацією Mermaid, щоб отримати пояснення та приклади.

Найважливіше — Робіть діаграми простими. Це заощадить час вам і вашим колегам-учасникам, а також полегшить читання для нових та досвідчених користувачів.

4 - Написання нової теми

Ця сторінка показує, як створити нову тему для документації Kubernetes.

Перш ніж ви розпочнете

Створіть форк репозиторію документації Kubernetes, як описано в розділі Створення PR.

Вибір типу сторінки

Перед тим, як почати писати нову тему, подумайте про тип сторінки, який найкраще підходить для вашого контенту:

Створення нової сторінки

Використовуйте тип контенту для кожної нової сторінки, яку ви пишете. Сайт документації надає шаблони або Hugo archetypes для створення нових сторінок контенту. Щоб створити нову сторінку, запустіть команду hugo new з шляхом до файлу, який ви хочете створити. Наприклад:

hugo new docs/concepts/my-first-concept.md

Вибір заголовка та імені файлу

Виберіть заголовок, який містить ключові слова, за якими ви хочете, щоб пошукові системи знаходили вашу сторінку. Створіть імʼя файлу, використовуючи слова в заголовку, розділені дефісами. Наприклад, тема з заголовком Використання HTTP-проксі для доступу до API Kubernetes має імʼя файлу http-proxy-access-api.md. Вам не потрібно додавати слово "kubernetes" в імʼя файлу, оскільки "kubernetes" вже є в URL для теми, наприклад:

/docs/tasks/extend-kubernetes/http-proxy-access-api/

Додавання заголовка теми до метаданих front matter

У вашій темі додайте поле title до метаданих. Метадані — це блок YAML, який знаходиться між потрійними рисками на початку сторінки. Ось приклад:

---
title: Використання HTTP-проксі для доступу до API Kubernetes
---

Вибір теки

Залежно від типу сторінки, розмістіть ваш новий файл у підтеці однієї з тек:

• /content/en/docs/tasks/
• /content/en/docs/tutorials/
• /content/en/docs/concepts/

Ви можете розмістити свій файл у наявній підтеці або створити нову підтекуг.

Розміщення вашої теми в таблиці змісту

Таблиця змісту створюється динамічно, використовуючи структуру тек вихідного коду документації. Теки верхнього рівня у /content/en/docs/ створюють навігацію верхнього рівня, а підтеки мають власні записи в таблиці змісту.

Кожна підтека має файл _index.md, який представляє "домашню" сторінку для контенту даної підтеки. _index.md не потребує шаблону. Він може містити оглядовий контент про теми в теці.

Інші файли в теці зазвичай сортуються в алфавітному порядку. Це майже ніколи не є найкращим випадком. Щоб контролювати відносне сортування тем у підтеці, встановіть в ключ метаданих weight: значення, ціле число. Зазвичай ми використовуємо кратні 10, щоб врахувати додавання тем пізніше. Наприклад, тема з вагою 10 буде розташована перед темою з вагою 20.

Вбудовування коду у вашу тему

Якщо ви хочете включити якийсь код у вашу тему, ви можете вбудувати код безпосередньо у файл, використовуючи синтаксис блоку коду markdown. Це рекомендується в таких випадках (не вичерпний список):

• Код показує вивід з команди, наприклад kubectl get deploy mydeployment -o json | jq '.status'.
• Код недостатньо загальний для того, щоб користувачі могли його випробувати. Наприклад, ви можете вбудувати YAML файл для створення Pod, який залежить від конкретної реалізації FlexVolume.
• Код є неповним прикладом, оскільки його мета — підкреслити частину великого файлу. Наприклад, при описі способів налаштування RoleBinding, ви можете надати короткий фрагмент безпосередньо у вашому файлі теми.
• Код не призначений для того, щоб користувачі його випробовували з інших причин. Наприклад, коли ви описуєте, як новий атрибут має бути доданий до ресурсу за допомогою команди kubectl edit, ви можете надати короткий приклад, який містить лише атрибут для додавання.

Включення коду з іншого файлу

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

При додаванні нового самостійного зразка файлу, такого як YAML файл, розмістіть код в одній з підтек <LANG>/examples/, де <LANG> — це мова для теми. У файлі вашої теми використовуйте shortcode code_sample:

{{% code_sample file="<RELPATH>/my-example-yaml>" %}}

де <RELPATH> — це шлях до файлу, який потрібно включити, відносно теки examples. Наступний shortcode Hugo посилається на YAML файл, розташований за адресою /content/en/examples/pods/storage/gce-volume.yaml.

{{% code_sample file="pods/storage/gce-volume.yaml" %}}

Показ як створити обʼєкт API з файлу конфігурації

Якщо вам потрібно продемонструвати, як створити обʼєкт API на основі файлу конфігурації, розмістіть файл конфігурації в одній з підтек у <LANG>/examples.

У вашій темі вкажіть цю команду:

kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml

Для прикладу теми, яка використовує цей прийом, див. Запуск Stateful застосунку в одному екземплярі.

Додавання зображень до теми

Розмістіть файли зображень у теці /images. Переважний формат зображення — SVG.

Що далі

• Дізнайтеся про використання типів контенту сторінок.
• Дізнайтеся про створення pull request.

5 - Типи контенту сторінок

Документація Kubernetes містить кілька типів контенту сторінок:

• Concept (Концепт)
• Task (Завдання)
• Tutorial (Посібник)
• Reference (Довідка)

Розділи контенту

Кожен тип контенту сторінок містить кілька розділів, визначених коментарями Markdown і HTML-заголовками. Ви можете додати заголовки контенту до вашої сторінки за допомогою shortcode heading. Коментарі та заголовки допомагають підтримувати структуру типів контенту сторінок.

Приклади коментарів Markdown, що визначають розділи контенту сторінки:

<!-- overview -->

<!-- body -->

Щоб створити загальні заголовки на ваших контентних сторінках, використовуйте body heading із рядком заголовка.

Приклади рядків заголовків:

• whatsnext (що далі)
• prerequisites (вимоги)
• objectives (цілі)
• cleanup (очищення)
• synopsis (синопсис)
• seealso (див. також)
• options (параметри)

Наприклад, щоб створити заголовок whatsnext, додайте shortcode із рядком "whatsnext":

## {{% heading "whatsnext" %}}

Щоб створити заголовок prerequisites, скористайтеся таким shortcode:

## {{% heading "prerequisites" %}}

Shortcode heading очікує один строковий параметр. Рядок заголовка відповідає префіксу змінної у файлах i18n/<lang>.toml. Наприклад:

i18n/en.toml:

[whatsnext_heading]
other = "What's next"

i18n/ko.toml:

[whatsnext_heading]
other = "다음 내용"

Типи контенту

Кожен тип контенту неформально визначає свою очікувану структуру сторінки. Створюйте контент сторінки, використовуючи рекомендовані розділи сторінок.

Концепт

Сторінка концепту пояснює певний аспект Kubernetes. Наприклад, сторінка концепту може описувати обʼєкт Kubernetes Deployment і пояснювати його роль як застосунку під час розгортання, масштабування та оновлення. Зазвичай сторінки концептів не містять послідовностей кроків, а натомість надають посилання на завдання або посібники.

Щоб написати нову сторінку концепту, створіть файл Markdown у підтеці content/en/docs/concepts з такими характеристиками:

Сторінки концептів поділяються на три розділи:

Розділи overview і body зʼявляються як коментарі на сторінці концепту. Ви можете додати розділ whatsnext на вашу сторінку за допомогою shortcode heading.

Заповніть кожен розділ контентом. Дотримуйтесь цих вказівок:

• Організуйте контент за допомогою заголовків H2 і H3.
• Для розділу overview задайте контекст теми одним абзацом.
• У розділі body поясніть концепцію.
• Для розділу whatsnext надайте список із кількох пунктів для подальшого вивчення теми.

Приклад опублікованої сторінки концепту: Анотації.

Завдання

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

Щоб написати нову сторінку завдання, створіть файл Markdown у підтеці /content/en/docs/tasks з такими характеристиками:

Розділи overview, steps і discussion зʼявляються як коментарі на сторінці завдання. Ви можете додати розділи prerequisites і whatsnext на вашу сторінку за допомогою shortcode heading.

У кожному розділі напишіть ваш контент, використовуючи такі вказівки:

• Використовуйте мінімум заголовків H2 (з двома символами # на початку). Самі розділи мають заголовки, які автоматично додаються шаблоном.
• У розділі overview використовуйте абзац для встановлення контексту для всієї теми.
• У розділі prerequisites використовуйте списки з пунктами, де це можливо. Додаткові вимоги додавайте під include. Стандартні вимоги включають працюючий кластер Kubernetes.
• У розділі steps використовуйте пронумеровані списки.
• У розділі discussion використовуйте звичайний контент для розширення інформації, про яку йдеться у розділі steps.
• У розділі whatsnext надайте список із кількох тем, які можуть зацікавити читача далі.

Приклад опублікованої сторінки завдання: Використання HTTP-проксі для доступу до API Kubernetes.

Посібник

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

Щоб написати нову сторінку посібника, створіть файл Markdown у підтеці /content/en/docs/tutorials з такими характеристиками:

Розділи overview, objectives і lessoncontent зʼявляються як коментарі на сторінці посібника. Ви можете додати розділи prerequisites, cleanup і whatsnext на вашу сторінку за допомогою shortcode heading.

У кожному розділі напишіть ваш контент, використовуючи такі вказівки:

• Використовуйте мінімум заголовків H2 (з двома символами # на початку). Самі розділи мають заголовки, які автоматично додаються шаблоном.
• У розділі overview використовуйте абзац для встановлення контексту для всієї теми.
• У розділі prerequisites використовуйте списки з пунктами, де це можливо. Додаткові вимоги додавайте під include.
• У розділі objectives використовуйте списки з пунктами.
• У розділі lessoncontent використовуйте комбінацію пронумерованих списків і наративного контенту, де це доречно.
• У розділі cleanup використовуйте пронумеровані списки для опису кроків, необхідних для очищення стану кластера після завершення завдання.
• У розділі whatsnext надайте список із кількох тем, які можуть зацікавити читача далі.

Приклад опублікованої сторінки посібника: Запуск застосунку без збереження стану за допомогою Deployment.

Довідка

Сторінка довідки інструмента компонента показує опис і параметри прапорців для інструмента компонента Kubernetes. Кожна сторінка генерується зі скриптів із використанням команд інструмента компонента.

Сторінка довідки з інструмента має кілька можливих розділів:

Приклади опублікованих сторінок довідки з інструмента:

• kubeadm init
• kube-apiserver
• kubectl

Що далі

• Дізнайтеся про настанови зі стилю
• Дізнайтеся про настанови з контенту
• Дізнайтеся про організацію контенту

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

Цей сайт використовує Hugo. В Hugo організація контенту є основним концептом.

Списки сторінок

Порядок сторінок

Бічне меню документації, оглядач сторінок документації тощо формуються за допомогою стандартного порядку сортування Hugo, який сортує за вагою (починаючи з 1), датою (новіші перші), і нарешті за заголовком посилання.

Щоб перемістити сторінку або розділ вверх, задайте вагу у front matter сторінки:

title: My Page
weight: 10

Основне меню документації

Основне меню Документація формується з розділів, що знаходяться в docs/, з прапорцем main_menu, встановленим у front matter файлу контенту _index.md:

main_menu: true

Зверніть увагу, що заголовок посилання береться з linkTitle сторінки, тому, якщо ви хочете, щоб він був відмінним від заголовка, змініть його у файлі контенту:

main_menu: true
title: Page Title
linkTitle: Title used in links

Бічне меню документації

Бічне меню документації формується з поточного дерева розділів в docs/.

Воно відображатиме всі розділи та їх сторінки.

Якщо ви не хочете відображати розділ або сторінку, встановіть прапорець toc_hide в значення true у front matter:

toc_hide: true

Коли ви переходите до розділу, який має контент, показується конкретний розділ або сторінка (наприклад, _index.md). Інакше показується перша сторінка всередині цього розділу.

Оглядач сторінок документації

Оглядач сторінок на домашній сторінці документації формується з усіх розділів і сторінок, які безпосередньо знаходяться нижче розділу docs.

Якщо ви не хочете відображати розділ або сторінку, встановіть прапорець toc_hide в значення true у front matter:

toc_hide: true

Основне меню

Посилання сайту в меню у верхньому правому куті, а також у нижньому колонтитулі, формуються за допомогою перегляду сторінок. Це робиться для того, щоб переконатися, що сторінка дійсно існує. Тому, якщо розділ case-studies не існує на сайті (для мови), він не буде показаний.

Пакети сторінок

Окрім окремих контентних сторінок (файли Markdown), Hugo підтримує Пакети сторінок.

Один приклад — Custom Hugo Shortcodes. Це вважається leaf bundle. Все, що знаходиться нижче теки, включаючи index.md, буде частиною пакета. Це також включає посилання, що є відносними до сторінки, зображення, які можна обробити тощо:

en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json

Ще один широко використовуваний приклад — пакет includes. Він встановлює headless: true у front matter, що означає, що він не отримує власний URL. Він використовується тільки в інших сторінках.

en/includes
├── default-storage-class-prereqs.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md

Декілька важливих приміток до файлів у пакетах:

• Для перекладених пакетів будь-які відсутні не контентні файли будуть успадковані з мов, що знаходяться вище. Це запобігає дублюванню.
• Усі файли в пакеті є тим, що Hugo називає Resources, і ви можете надавати метадані для кожної мови, такі як параметри і заголовок, навіть якщо це не підтримує front matter (YAML файли тощо). Див. Метадані ресурсів сторінок.
• Значення, яке ви отримуєте з .RelPermalink Resource є відносним до сторінки. Див. Permalinks.

Стилі

Джерело стилів SASS для цього сайту зберігається у assets/sass і автоматично будується Hugo.

Що далі

• Дізнайтеся про власні shortcodes Hugo
• Дізнайтеся про настанови зі стилю
• Дізнайтеся про настанови з контенту

7 - Власні shortcodes Hugo

Ця сторінка пояснює, як використовувати shortcodes Hugo в документації Markdown для Kubernetes.

Детальніше про shortcodes можна дізнатися в документації Hugo.

Стан функції

На сторінці Markdown (.md файл) на цьому сайті ви можете додати shortcodes для відображення версії та стану документованої функції.

Демонстрація стану функції

Нижче наведено демонстрацію фрагмента стану функції, який відображає функцію як стабільну в останній версії Kubernetes.

{{< feature-state state="stable" >}}

Показується як:

Дійсні значення для state:

• alpha
• beta
• deprecated
• stable

Код стану функції

Показана версія Kubernetes типово є версією сторінки або сайту. Ви можете змінити версію стану функції, передавши параметр for_k8s_version для shortcode. Наприклад:

{{< feature-state for_k8s_version="v1.10" state="beta" >}}

Показується як:

Отримання стану функції з файлу опису

Щоб динамічно визначити стан функції, використовуйте параметр feature_gate_name. Деталі стану функції будуть витягнуті з відповідного файлу опису функціональних можливостей розташованого в content/en/docs/reference/command-line-tools-reference/feature-gates/. Наприклад:

{{< feature-state feature_gate_name="NodeSwap" >}}

Показується як:

Опис функціональних можливостей

На сторінці Markdown (.md файл) на цьому сайті ви можете додати код для показу опису функціональної можливості.

Демонстрація опису функціональної можливості

Нижче наведено демонстрацію фрагмента опису функціональної можливості, який показує функцію як стабільну в останній версії Kubernetes.

{{< feature-gate-description name="DryRun" >}}

Показується як:

DryRun: Вмикає запити dry rin на боці сервера, щоб можна було тестувати валідацію, злиття та мутацію без впровадження змін.

Глосарій

Існують два коротких коди для глосарія: glossary_tooltip та glossary_definition.

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

Окрім включень з підказками, ви можете повторно використовувати визначення з глосарія у вмісті сторінки.

Дані для термінів глосарія зберігаються в теці глосарія, з файлом вмісту для кожного терміна глосарія.

Демонстрація глосарія

Наприклад, наступне включення в Markdown показується для терміна кластер з підказкою:

{{< glossary_tooltip text="cluster" term_id="cluster" >}}

Ось коротке визначення глосарія:

{{< glossary_definition prepend="Кластер — " term_id="cluster" length="short" >}}

яке показується як:

Кластер — набір робочих машин, що називаються вузлами, які виконують контейнеризовані застосунки. Кожен кластер має принаймні один робочий вузол.

Ви також можете включити повне визначення:

{{< glossary_definition term_id="cluster" length="all" >}}

яке показується як:

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

Робочі вузли містять Podʼи, які є компонентами навантаження застосунку. Панель управління керує робочими вузлами та Podʼами в кластері. В операційних середовищах панель управління, зазвичай, працює на кількох компʼютерах, і кластер, як правило, має кілька вузлів, забезпечуючи стійкість до відмов та високу доступність.

Посилання на довідник API

Ви можете створити посилання на сторінку довідника API Kubernetes, використовуючи короткий код api-reference, наприклад, на довідник Pod:

{{< api-reference page="workload-resources/pod-v1" >}}

Вміст параметра page є суфіксом URL сторінки довідника API.

Ви можете посилатися на конкретне місце на сторінці, вказавши параметр anchor, наприклад, на довідник PodSpec або розділ environment-variables сторінки:

{{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}}
{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}}

Ви можете змінити текст посилання, вказавши параметр text, наприклад, посилаючись на Змінні оточення розділ сторінки:

{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Змінні оточення" >}}

Заголовки таблиць

Ви можете зробити таблиці більш доступними для екранних зчитувачів, додавши заголовок таблиці. Щоб додати заголовок до таблиці, оберніть таблицю кодом table і вкажіть заголовок за допомогою параметра caption.

Ось приклад:

{{< table caption="Configuration parameters" >}}
Parameter | Description | Default
:---------|:------------|:-------
`timeout` | The timeout for requests | `30s`
`logLevel` | The log level for log output | `INFO`
{{< /table >}}

Показується як:

Якщо ви переглянете HTML для таблиці, ви повинні побачити цей елемент одразу після відкриваючого елемента <table>:

<caption style="display: none;">Configuration parameters</caption>

Вкладки

На сторінці Markdown (.md файл) на цьому сайті ви можете додати набір вкладок для показу різних варіантів рішення.

Короткий код tabs приймає такі параметри:

• name: Ім’я, яке відображається на вкладці.
• codelang: Якщо ви надаєте внутрішній вміст для короткого коду tab, ви можете вказати Hugo, яку мову коду використовувати для підсвічування.
• include: Файл для включення у вкладку. Якщо вкладка знаходиться в Hugo leaf bundle, файл, який може бути будь-якого MIME типу, підтримуваного Hugo, шукається у самому пакеті. Якщо ні, сторінка вмісту, яку потрібно включити, шукається відносно поточної сторінки. Зверніть увагу, що з include у вас немає внутрішнього вмісту shortcode і ви повинні використовувати синтаксис самозакриваючих теґів. Наприклад, {{< tab name="Content File #1" include="example1" />}}. Мову потрібно вказати у codelang, або мова буде визначена на основі імені файлу. Ффайли non-content стандартно підсвічуються як код.
• Якщо ваш внутрішній вміст є Markdown, ви повинні використовувати роздільник % для оточення вкладки. Наприклад, {{% tab name="Tab 1" %}}This is **markdown**{{% /tab %}}
• Ви можете комбінувати зазначені вище варіації всередині набору вкладок.

Нижче наведено демонстрацію shortcode вкладок.

Демонстрація вкладок: Підсвічування коду

{{< tabs name="tab_with_code" >}}
{{< tab name="Tab 1" codelang="bash" >}}
echo "This is tab 1."
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "This is tab 2."
{{< /tab >}}
{{< /tabs >}}

Показується як:

• Tab 1
• Tab 2

echo "This is tab 1."

println "This is tab 2."

Демонстрація вкладок: Вбудований Markdown та HTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
This is **some markdown.**
{{< note >}}
It can even contain shortcodes.
{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
	<h3>Plain HTML</h3>
	<p>This is some <i>plain</i> HTML.</p>
</div>
{{< /tab >}}
{{< /tabs >}}

Показується як:

• Markdown
• HTML

Демонстрація вкладок: Включення файлів

{{< tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}}
{{< /tabs >}}

Показується як:

• Content File #1
• Content File #2
• JSON File

{
    "apiVersion": "v1",
    "kind": "PodTemplate",
    "metadata": {
      "name": "nginx"
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "nginx"
        },
        "generateName": "nginx-"
      },
      "spec": {
         "containers": [{
           "name": "nginx",
           "image": "dockerfile/nginx",
           "ports": [{"containerPort": 80}]
         }]
      }
    }
  }

Файли вихідного коду

Ви можете використовувати код {{% code_sample %}} для вбудовування вмісту файлу в кодовий блок, щоб користувачі могли завантажити або скопіювати його вміст у буфер обміну. Цей код використовується, коли вміст зразкового файлу є загальним і багаторазовим, і ви хочете, щоб користувачі могли спробувати його самостійно.

Цей короткий код приймає два іменованих параметри: language та file. Обов’язковий параметр file використовується для вказання шляху до файлу, який відображається. Опційний параметр language використовується для вказання мови програмування файлу. Якщо параметр language не надано, код намагатиметься вгадати мову на основі розширення файлу.

Наприклад:

{{% code_sample language="yaml" file="application/deployment-scale.yaml" %}}

Вихідний результат:

application/deployment-scale.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 4 # Update the replicas from 2 to 4
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.16.1
        ports:
        - containerPort: 80

Коли ви додаєте новий зразковий файл, наприклад YAML файл, створіть файл в одній з підтек <LANG>/examples/, де <LANG> — це мова для сторінки. У Markdown вашої сторінки використовуйте код code:

{{% code_sample file="<RELATIVE-PATH>/example-yaml>" %}}

де <RELATIVE-PATH> — шлях до зразкового файлу, який потрібно включити, відносно теки examples. Наступний код посилається на YAML файл, розташований за адресою /content/en/examples/configmap/configmaps.yaml.

{{% code_sample file="configmap/configmaps.yaml" %}}

Застарілий код {{% codenew %}} замінюється на {{% code_sample %}}. Використовуйте {{% code_sample %}} (а не {{% codenew %}} чи {{% code %}}) у новій документації.

Маркер контенту третіх сторін

Для роботи з Kubernetes потрібно стороннє програмне забезпечення. Наприклад, вам зазвичай потрібно додати DNS-сервер до вашого кластера, щоб забезпечити правильну роботу розпізнавання імен.

Коли ми посилаємося на стороннє програмне забезпечення або згадуємо про нього, ми дотримуємося керівництва з контенту і також позначаємо ці сторонні елементи.

Використання цих shortcodes додає відмову від відповідальності до будь-якої сторінки документації, яка їх використовує.

Списки

Для списку кількох сторонніх елементів додайте:

{{% thirdparty-content %}}

відразу після заголовка розділу, що включає всі елементи.

Елементи

Якщо у вас є список, в якому більшість елементів належать до програмного забезпечення проєкту (наприклад: сам Kubernetes, і окремий компонент Descheduler), то є інша форма для використання.

Додайте короткий код:

{{% thirdparty-content single="true" %}}

перед елементом або відразу після заголовка для конкретного елемента.

Деталі

Ви можете відобразити HTML елемент <details> за допомогою шорткоду:

{{< details summary="Детальніше про віджети" >}}
API розширення frobnicator реалізує _віджети_ із використанням тексту прикладу.

Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.
{{< /details >}}

Це буде показано так:

Рядки версій

Щоб створити рядок версії для включення в документацію, ви можете вибрати з кількох shortcode для версії. Кожен код версії відображає рядок версії, отриманий зі значення параметра версії, знайденого у файлі конфігурації сайту, hugo.toml. Два найбільш часто використовуваних параметри версії — це latest і version.

{{< param "version" >}}

Код {{< param "version" >}} генерує значення поточної версії документації Kubernetes з параметра сайту version. Код param приймає назву одного параметра сайту, в цьому випадку: version.

Показується як:

{{< latest-version >}}

Код {{< latest-version >}} повертає значення параметра сайту latest. Параметр сайту latest оновлюється, коли випускається нова версія документації. Цей параметр не завжди відповідає значенню version у наборі документації.

Показується як:

{{< latest-semver >}}

Короткий код {{< latest-semver >}} генерує значення latest без префікса "v".

Показується як:

{{< version-check >}}

Код {{< version-check >}} перевіряє, чи присутній параметр min-kubernetes-server-version на сторінці, а потім використовує це значення для порівняння з version.

Показується як:

{{< latest-release-notes >}}

Код {{< latest-release-notes >}} генерує рядок версії з latest і видаляє префікс "v". Короткий код друкує нове посилання на сторінку з нотатками про випуски з модифікованим рядком версії.

Показується як:

Що далі

• Дізнайтеся про Hugo.
• Дізнайтеся про створення нової теми.
• Дізнайтеся про типи вмісту сторінок.
• Дізнайтеся про відкриття pull request.
• Дізнайтеся про розширений варіант участі.