Вы просматриваете документацию для Kubernetes версии: v1.30
Kubernetes v1.30 документация больше не поддерживается. Версия, которую вы сейчас просматриваете, является статической. Для актуальной документации см. последнюю версию.
Использование шаблонов страниц
При добавлении новых тем воспользуйтесь одним из перечисленных ниже шаблонов. Это регламентирует пользовательское восприятие определённой страницы.
Шаблоны страниц находятся в директории layouts/partials/templates
репозитория kubernetes/website
.
Примечание:
Каждая новая тема должна использовать шаблон. Если вы не уверены, какой шаблон использовать для новой темы, начните с шаблона концепции.Шаблон концепции
Страница концепции объясняет некоторые аспекты Kubernetes. Например, страницы концепции может описывать объект Deployment в Kubernetes и разъяснить какую роль он играет после развертывания, масштабирования и обновления приложения. Как правило, страницы концепций не включают последовательности шагов, и вместо этого содержат ссылки на задачи или руководства.
Для написания новой страницы концепции в директории /content/en/docs/concepts
создайте поддиректорию с Markdown-файлом со следующим требованиями:
-
Во фронтальной части YAML этой страницы определите поле
content_type: concept
. -
В теле страницы укажите переменные
capture
и любые другие, которые вы хотите включить:Переменная Обязательна? overview да body да whatsnext нет Тело страницы будет выглядеть следующим образом (удалите все необязательные capture-блоки, если они вам не понадобятся):
{{% capture overview %}} {{% /capture %}} {{% capture body %}} {{% /capture %}} {{% capture whatsnext %}} {{% /capture %}}
-
Заполните каждый раздел информацией. Следуйте этим рекомендациям:
- Структурируйте контент с помощью заголовков H2 и H3.
- В блоке
overview
одним абзацем сформируйте контекст темы. - В блоке
body
объясните суть концепции. - В блоке
whatsnext
сформируйте ненумерованный список тем (до 5), к которым нужно обратиться, чтобы получить дополнительную информацию о концепции.
Annotations — это готовый пример шаблона концепции. Кстати, текущая страница использует шаблон концепции.
Шаблон задачи
На странице задачи показывается, как сделать что-то одно конкретное, главным образом с помощью короткой последовательности шагов. В страницах задач очень короткое объяснение, хотя они часто ссылаются на концептуальные темы, где уже можно найти соответствующую справочную информацию и ресурсы.
Для написания новой страницы задачи в директории /content/en/docs/tasks
создайте поддиректорию с Markdown-файлом со следующим требованиями:
-
Во фронтальной части YAML этой страницы определите поле
content_type: task
. -
В теле страницы укажите переменные
capture
и любые другие, которые вы хотите включить:Переменная Обязательна? overview да prerequisites да steps нет discussion нет whatsnext нет Тело страницы будет выглядеть следующим образом (удалите все необязательные capture-блоки, если они вам не нужны):
{{% capture overview %}} {{% /capture %}} {{% capture prerequisites %}} {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} {{% /capture %}} {{% capture steps %}} {{% /capture %}} {{% capture discussion %}} {{% /capture %}} {{% capture whatsnext %}} {{% /capture %}}
-
Заполните каждый блок информацией. Следуйте этим рекомендациям:
- Используйте по минимуму заголовков H2 (с двумя ведущими символами
#
). У самих разделов заголовок формируется автоматически по заданному шаблону. - В блоке
overview
обозначьте контекст для всей темы. - В блоке
prerequisites
используйте ненумерованные списки, где это возможно. Добавьте дополнительные предварительные условия нижеinclude
. Предварительные условия по умолчанию содержат пункт про наличие работающего кластера. - В блоке
steps
используйте нумерованные списки. - В блоке
discussion
подробно распишите информацию, описанную в разделеsteps
. - В блоке
whatsnext
сформируйте ненумерованный список тем (до 5), которые могут быть интересны читателю в качестве дополнительного чтения.
- Используйте по минимуму заголовков H2 (с двумя ведущими символами
Пример готовой темы, в которой используется шаблон задачи — Using an HTTP proxy to access the Kubernetes API.
Шаблон руководства
На странице руководства показывается, как выполнить что-то более крупнее одной-единственной задачи. Как правило, страницы руководства поделена на несколько разделов, в каждом из которых есть последовательность шагов. Например, руководство может включать анализ примера кода, демонстрирующий определенную возможность Kubernetes. Руководства могут содержать поверхностные объяснения и одновременно включать ссылки на соответствующие концептуальные темы для получения углубленных знаний.
Для написания новой страницы задачи в директории /content/en/docs/tutorials
создайте поддиректорию с Markdown-файлом со следующим требованиями:
-
Во фронтальной части YAML этой страницы определите поле
content_type: tutorial
. -
В теле страницы укажите переменные
capture
и любые другие, которые вы хотите включить:Переменная Обязательна? overview да prerequisites да objectives да lessoncontent да cleanup нет whatsnext нет Тело страницы будет выглядеть следующим образом (удалите все необязательные capture-блоки, если они вам не понадобятся):
{{% capture overview %}} {{% /capture %}} {{% capture prerequisites %}} {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} {{% /capture %}} {{% capture objectives %}} {{% /capture %}} {{% capture lessoncontent %}} {{% /capture %}} {{% capture cleanup %}} {{% /capture %}} {{% capture whatsnext %}} {{% /capture %}}
-
Заполните каждый блок информацией. Следуйте этим рекомендациям:
- Используйте по минимуму заголовков H2 (с двумя ведущими символами
#
). У самих разделов заголовок формируется автоматически по заданному шаблону. - В блоке
overview
обозначьте контекст для всей темы. - В блоке
prerequisites
используйте ненумерованные списки, где это возможно. Добавьте дополнительные предварительные условия нижеinclude
. Предварительные условия по умолчанию содержат пункт про наличие работающего кластера. - В блоке
objectives
используйте ненумерованные списки. - В блоке
lessoncontent
целесообразно используйте совместно нумерованные списки и повествовательное содержание. - В блоке
cleanup
используйте нумерованные списки для описания шагов для очистки состояния кластера после выполнения задачи. - В блоке
whatsnext
сформируйте ненумерованный список тем (до 5), которые могут быть интересны читателю в качестве дополнительного чтения.
- Используйте по минимуму заголовков H2 (с двумя ведущими символами
Пример завершенной темы, в которой используется шаблон руководства — Running a Stateless Application Using a Deployment.
Что дальше
- Подробнее про оформление документации
- Подробнее про содержание документации
- Подробнее про организацию контента