Матеріали цього розділу містять настанови щодо стилю написання, форматування та організації вмісту, а також використання специфічних для документації Kubernetes налаштувань 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 посилається на канонічні джерела замість розміщення вмісту з подвійним джерелом.
Вміст із подвійним джерелом потребує вдвічі більше зусиль (або й більше!) на підтримку і швидше застаріває.
Примітка:
Якщо ви супровідник проєкту Kubernetes і вам потрібна допомога з розміщенням власної документації, попросіть допомоги в #sig-docs у Kubernetes Slack.Додаткова інформація
Якщо у вас є запитання щодо дозволеного вмісту, приєднайтеся до каналу #sig-docs у Kubernetes Slack і запитайте!
Що далі
- Ознайомтеся з посібником зі стилю.
2 - Організація контенту
Цей сайт використовує Hugo. У Hugo організація вмісту — одне з ключових понять.
Примітка:
Порада щодо Hugo: для сеансів редагування вмісту запускайте Hugo командоюhugo server --navigateToChanged.Списки сторінок
Порядок сторінок
Бічне меню документації, браузер сторінок документації тощо впорядковуються за стандартним порядком сортування Hugo: за вагою (від 1), датою (спершу новіші) і, нарешті, за заголовком посилання.
Тож, якщо ви хочете перемістити сторінку або розділ вище, задайте вагу у front matter сторінки:
title: My Page
weight: 10
Примітка:
Для ваги сторінок розумно використовувати не 1, 2, 3 ..., а інший інтервал, скажімо, 10, 20, 30... Це дасть змогу згодом вставляти сторінки там, де потрібно. Крім того, ваги в межах однієї теки (розділу) не мають збігатися з іншими вагами. Так вміст завжди буде впорядковано правильно, особливо в локалізованому вмісті.Головне меню документації
Головне меню Документація формується з розділів у docs/, у front matter файлу вмісту розділу _index.md яких встановлено прапорець main_menu:
main_menu: true
Зверніть увагу, що заголовок посилання береться з linkTitle сторінки, тож якщо ви хочете, щоб він відрізнявся від заголовка, змініть його у файлі вмісту:
main_menu: true
title: Page Title
linkTitle: Title used in links
Примітка:
Це потрібно зробити для кожної мови. Якщо ви не бачите свого розділу в меню, імовірно, Hugo не визначає його як розділ. Створіть файл вмісту_index.md у теці розділу.Бічне меню документації
Бічне меню документації формується з поточного дерева розділів, починаючи нижче docs/.
У ньому відображаються всі розділи та їхні сторінки.
Якщо ви не хочете показувати розділ або сторінку в списку, встановіть прапорець toc_hide у true у front matter:
toc_hide: true
Коли ви переходите до розділу, що має вміст, показується конкретний розділ або сторінка (наприклад, _index.md). Інакше показується перша сторінка в цьому розділі.
Браузер документації
Браузер сторінок на домашній сторінці документації формується з усіх розділів і сторінок, розміщених безпосередньо нижче docs section.
Якщо ви не хочете показувати розділ або сторінку в списку, встановіть прапорець toc_hide у true у front matter:
toc_hide: true
Головне меню
Посилання сайту в меню вгорі праворуч (а також у нижньому колонтитулі) формуються через пошук сторінок. Так забезпечується, що сторінка справді існує. Тож якщо розділу case-studies на сайті (для мови) немає, посилання на нього не буде.
Пакети сторінок
Крім окремих сторінок вмісту (файлів Markdown), Hugo підтримує пакети сторінок.
Один із прикладів — Власні shortcodes Hugo. Це leaf bundle. Усе, що міститься в цій теці, зокрема index.md, буде частиною пакета. Це також стосується посилань відносно сторінки, зображень, які можна обробляти, тощо:
en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json
Ще один поширений приклад — пакет includes. У його front matter встановлено headless: true, тобто він не отримує власного 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
- Ознайомтеся з посібником зі стилю
- Ознайомтеся з посібником з вмісту