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

Документація 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

Що далі

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