Написание новой темы

На этой странице показано, как создать новую тему для документации Kubernetes.

Подготовка к работе

Создайте копию репозитория документации Kubernetes, как описано в разделе Участие для начинающих.

Выбор типы страницы

Перед написанием новой темы, выберите тип страницы, который бы лучше всего подходил под ваш текст:

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

Выбор заголовка и имени файла a title and filename

Подберите заголовок, содержащий такие ключевые слова, по которым вы могли его найти в поисковике. Имя файла должно создаваться из слов в заголовке, написанных через дефис. Например, для темы с заголовком Using an HTTP Proxy to Access the Kubernetes API имя файла будет http-proxy-access-api.md. Вам не нужно указывать "kubernetes" в имени файла, потому что слово "kubernetes" уже есть в полном URL-адресе темы, например:

   /docs/tasks/access-kubernetes-api/http-proxy-access-api/

Добавление заголовка темы в фронтальную часть

В фронтальную часть файла вашей темы поместите поле заголовка title. Фронтальная часть — YAML-блок, который находится тремя дефисами в самом верху страницы. Например:

---
title: Using an HTTP Proxy to Access the Kubernetes API
---

Выбор директории

В зависимости от типа вашей страницы поместите новый файл в одну из следующую поддиректорию:

• /content/en/docs/tasks/
• /content/en/docs/tutorials/
• /content/en/docs/concepts/

Вы можете поместить файл в имеющуюся поддиректорию либо создать новую.

Добавление темы в оглавлении

Оглавление динамически генерируется исходя из структуры директорий документации. Корневые директории в /content/en/docs/ создают навигацию с основными ссылками, где у каждой поддиректории есть записи в оглавлении.

В каждой поддиректории есть файл _index.md, представляющий собой "главную" страницу всего содержимого этой поддиректории. В файле _index.md не нужно применять шаблон. В нём находится обзор содержания тем в поддиректории.

Другие файлы в директории по умолчанию сортируются в алфавитном порядке. Такой порядок сортировки редко устраивает. Для управления такой относительной сортировкой тем в поддиректории, определите ключ weight: с целым числом в фронтальной части файла. Как правило, мы используем значения, кратные 10, чтобы оставить про запас для будущих страниц. Например, тема с весом 10 будет отображаться перед темой с весом 20.

Вставка кода в тему

Если вы хотите добавить код в тему, вы можете встроить код из файла напрямую, используя синтаксис блока кода в Markdown. Такой способ рекомендуется использовать в следующих случаев (это не исчерпывающий список):

• В вашем коде показывается вывод такой команды, как kubectl get deploy mydeployment -o json | jq '.status'.
• Ваш код недостаточно универсален, чтобы пользователи могли его попробовать сами. В качестве примера можно привести пример YAML-файла для создания Pod, который зависит от конкретной реализации FlexVolume.
• Ваш код — это не готовый пример, потому что он предзначен для выделения части большего файла. Например, при описании способов настройки PodSecurityPolicy по определённым причинам вы можете включить небольшой фрагмент напрямую в файле темы.
• Ваш код по разным причинам не подходит для тестирования пользователями. Например, если вы описываете, как новый атрибут должен добавляться к ресурсу с помощью команды kubectl edit, то вы можете добавить короткий пример, показывающий только добавляемый атрибут.

Добавление кода из другого файла

Другой способ добавить код в вашу тему — создать новый полноценный файл с примером (или группу файлов примеров), а затем из вашей темы подключить этот пример. Используйте этот метод, чтобы включить универсальный и повторно используемый пример YAML-файла, который читатель может проверить сам.

При добавлении нового отдельного файла примера, например, в формате YAML, поместите код в одну из директорий <LANG>/examples/, где <LANG> — язык темы. В вашем файле темы используйте макрокод codenew:

{{% codenew file="<RELPATH>/my-example-yaml>" %}}

где <RELPATH> — это путь к включаемому файлу относительно директории examples. Следующий макрокод Hugo ссылается на YAML-файл по пути /content/en/examples/pods/storage/gce-volume.yaml.

{{% codenew file="pods/storage/gce-volume.yaml" %}}

Демонстрация создания API-объекта из конфигурационного файла

Если вам нужно показать, как создать объект API из файла конфигурации, поместите файл конфигурации в одну из директорий в <LANG>/examples.

В вашей теме укажите эту команду:

kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml

В качестве примера темы, в которой используется этот метод, смотрите Running a Single-Instance Stateful Application.

Добавление изображений в тему

Поместите файлы изображений в директорию /images. Предпочтительный формат изображения — SVG.

Что дальше

• Подробнее про использование шаблонов страниц.
• Подробнее про создание пулреквеста).