website/content/ru/docs/contribute/style/page-templates.md

title, content_template, weight, card

title	content_template	weight	card
Использование шаблонов страниц	templates/concept	30	name weight contribute 30

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

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

{{< note >}} Каждая новая тема должна использовать шаблон. Если вы не уверены, какой шаблон использовать для новой темы, начните с шаблона концепции. {{< /note >}}

{{% /capture %}}

{{% capture body %}}

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

Страница концепции объясняет некоторые аспекты 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.

{{% /capture %}}

{{% capture whatsnext %}}

• Подробнее про оформление документации
• Подробнее про содержание документации
• Подробнее про организацию контента

{{% /capture %}}