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

Ця сторінка показує, як створити нову тему для документації 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.