Translate Documentation style overview section into Russian (#19521)
This commit is contained in:
Alexey Pyltsyn
@@ -0,0 +1,186 @@
|
||||
---
|
||||
title: Использование шаблонов страниц
|
||||
content_template: templates/concept
|
||||
weight: 30
|
||||
card:
|
||||
name: contribute
|
||||
weight: 30
|
||||
---
|
||||
|
||||
{{% capture overview %}}
|
||||
При добавлении новых тем воспользуйтесь одним из перечисленных ниже шаблонов.
|
||||
Это регламентирует пользовательское восприятие определённой страницы.
|
||||
|
||||
Шаблоны страниц находятся в директории [`layouts/partials/templates`](https://git.k8s.io/website/layouts/partials/templates) репозитория [`kubernetes/website`](https://github.com/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](/docs/concepts/overview/working-with-objects/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](/docs/tasks/access-kubernetes-api/http-proxy-access-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](/docs/tutorials/stateless-application/run-stateless-application-deployment/).
|
||||
|
||||
{{% /capture %}}
|
||||
|
||||
{{% capture whatsnext %}}
|
||||
|
||||
- Подробнее про [оформление документации](/ru/docs/contribute/style/style-guide/)
|
||||
- Подробнее про [содержание документации](/ru/docs/contribute/style/content-guide/)
|
||||
- Подробнее про [организацию контента](/ru/docs/contribute/style/content-organization/)
|
||||
|
||||
{{% /capture %}}
|
||||
Reference in New Issue
Block a user