Участие в документации Kubernetes

Edit This Page

Использование шаблонов страниц

При добавлении новых тем воспользуйтесь одним из перечисленных ниже шаблонов. Это регламентирует пользовательское восприятие определённой страницы.

Шаблоны страниц находятся в директории layouts/partials/templates репозитория kubernetes/website.

Заметка: Каждая новая тема должна использовать шаблон. Если вы не уверены, какой шаблон использовать для новой темы, начните с шаблона концепции.

Шаблон концепции

Страница концепции объясняет некоторые аспекты Kubernetes. Например, страницы концепции может описывать объект Deployment в Kubernetes и разъяснить какую роль он играет после развертывания, масштабирования и обновления приложения. Как правило, страницы концепций не включают последовательности шагов, и вместо этого содержат ссылки на задачи или руководства.

Для написания новой страницы концепции в директории /content/en/docs/concepts создайте поддиректорию с Markdown-файлом со следующим требованиями:

  • Во фронтальной части YAML этой страницы определите поле content_template: templates/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_template: templates/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_template: templates/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.

Что дальше

Обратная связь