Ця сторінка показує, як створити нову тему для документації Kubernetes.
Створіть форк репозиторію документації Kubernetes, як описано в розділі Створення PR.
Перед тим, як почати писати нову тему, подумайте про тип сторінки, який найкраще підходить для вашого контенту:
| Тип | Опис |
|---|---|
| Concept | Сторінка концепту пояснює певний аспект Kubernetes. Наприклад, сторінка концепту може описувати обʼєкт Kubernetes Deployment і пояснювати його роль як застосунку під час його розгортання, масштабування та оновлення. Зазвичай сторінки концептів не містять послідовностей кроків, але натомість надають посилання на завдання або підручники. Для прикладу теми концепту, див. Вузли. |
| Task | Сторінка завдання показує, як виконати одне конкретне завдання. Ідея полягає в тому, щоб надати читачам послідовність кроків, які вони можуть виконати під час читання сторінки. Сторінка завдання може бути короткою або довгою, за умови, що вона зосереджена на одній темі. На сторінці завдання можна поєднувати короткі пояснення з кроками, які потрібно виконати, але якщо вам потрібно надати докладне пояснення, ви повинні зробити це в темі концепту. Повʼязані теми завдань і концептів повинні посилатися одна на одну. Для прикладу короткої сторінки завдання див. Налаштування контейнера Pod для використання тому для зберігання. Для прикладу довшої сторінки завдання див. Налаштування проб для перевірки працездатності та готовності. |
| Tutorial | Сторінка підручника показує, як досягти мети, яка обʼєднує кілька функцій Kubernetes. Підручник може містити кілька послідовностей кроків, які читачі можуть виконувати під час читання сторінки. Або він може надавати пояснення повʼязаних фрагментів коду. Наприклад, підручник може надати покроковий огляд зразка коду. Підручник може включати короткі пояснення функцій Kubernetes, які обʼєднуються, але повинен посилатися на відповідні теми концептів для детального пояснення окремих функцій. |
Використовуйте тип контенту для кожної нової сторінки, яку ви пишете. Сайт документації надає шаблони або 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/
У вашій темі додайте поле title до метаданих. Метадані — це блок YAML, який знаходиться між потрійними рисками на початку сторінки. Ось приклад:
---
title: Використання HTTP-проксі для доступу до API Kubernetes
---
Залежно від типу сторінки, розмістіть ваш новий файл у підтеці однієї з тек:
Ви можете розмістити свій файл у наявній підтеці або створити нову підтекуг.
Таблиця змісту створюється динамічно, використовуючи структуру тек вихідного коду документації. Теки верхнього рівня у /content/en/docs/ створюють навігацію верхнього рівня, а підтеки мають власні записи в таблиці змісту.
Кожна підтека має файл _index.md, який представляє "домашню" сторінку для контенту даної підтеки. _index.md не потребує шаблону. Він може містити оглядовий контент про теми в теці.
Інші файли в теці зазвичай сортуються в алфавітному порядку. Це майже ніколи не є найкращим випадком. Щоб контролювати відносне сортування тем у підтеці, встановіть в ключ метаданих weight: значення, ціле число. Зазвичай ми використовуємо кратні 10, щоб врахувати додавання тем пізніше. Наприклад, тема з вагою 10 буде розташована перед темою з вагою 20.
Якщо ви хочете включити якийсь код у вашу тему, ви можете вбудувати код безпосередньо у файл, використовуючи синтаксис блоку коду markdown. Це рекомендується в таких випадках (не вичерпний список):
kubectl get deploy mydeployment -o json | jq '.status'.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 на основі файлу конфігурації, розмістіть файл конфігурації в одній з підтек у <LANG>/examples.
У вашій темі вкажіть цю команду:
kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml
<LANG>/examples, переконайтеся, що файл також включено до файлу <LANG>/examples_test.go. Система Travis CI для вебсайту автоматично запускає цей тест, коли подаються PR, щоб переконатися, що всі приклади проходять тести.Для прикладу теми, яка використовує цей прийом, див. Запуск Stateful застосунку в одному екземплярі.
Розмістіть файли зображень у теці /images. Переважний формат зображення — SVG.