Вы просматриваете документацию для 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), которые могут быть интересны читателю в качестве дополнительного чтения.

Пример готовой темы, в которой используется шаблон задачи — 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), которые могут быть интересны читателю в качестве дополнительного чтения.

Пример завершенной темы, в которой используется шаблон руководства — Running a Stateless Application Using a Deployment.

Что дальше

Изменено June 01, 2020 at 9:17 AM PST: add ru pages (1224efaa6f)