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

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

Шаблоны страниц находятся в директории 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.

Что дальше

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