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

Повернутися до звичайного перегляду сторінки.

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

Матеріали цього розділу містять настанови щодо стилю написання, форматування та організації вмісту, а також використання специфічних для документації 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.

Що далі