Пользовательские макрокоды Hugo

На этой странице объясняются пользовательские макрокоды Hugo, которые можно использовать в Markdown-файлах документации Kubernetes.

Узнать подробнее про макрокоды можно в документации Hugo.

Состояние функциональности
Глоссарий
Заголовки таблиц
Вкладки
Что дальше

Состояние функциональности

В Markdown странице (файл с расширением .md) вы можете добавить макрокод, чтобы отобразить версию и состояние документированной функциональной возможности.

Демонстрация состояния функциональности

Ниже показан фрагмент кода для вывода состояния функциональности, который сообщает о функциональности в стабильной версии Kubernetes 1.10.

{{< feature-state for_k8s_version="v1.10" state="stable" >}}

Результат:

FEATURE STATE: Kubernetes v1.10 stable

Данная функциональность является стабильной, это означает, что:

Версии именуются по шаблону vX, где X — это целое число.
Стабильные версии функциональности будут доступны во многих последующих выпусках.

Допустимые значения для state:

alpha
beta
deprecated
stable

Код состояния функциональности

По умолчанию отображается версия Kubernetes, соответствующая версии страницы или сайта. Это значение можно переопределить, передав параметр макрокода for_k8s_version.

{{< feature-state for_k8s_version="v1.10" state="stable" >}}

Результат:

FEATURE STATE: Kubernetes v1.10 stable

Данная функциональность является стабильной, это означает, что:

Версии именуются по шаблону vX, где X — это целое число.
Стабильные версии функциональности будут доступны во многих последующих выпусках.

Функциональность в альфа-версии

{{< feature-state state="alpha" >}}

Результат:

FEATURE STATE: Kubernetes v1.17 alpha

В настоящее время данная функциональность находится в состоянии alpha, это означает, что:

Названия версий включают надпись “alpha” (например, v1alpha1).
Могут быть баги. Работа с этой функциональностью может привести к ошибкам. Поэтому по умолчанию она отключена.
Поддержка функциональности может быть прекращена в любое время без предупреждения.
API может быть несовместим с более поздними версиями без предупреждения.
Рекомендуется для использования только в тестировочных кластерах с коротким жизненным циклом из-за высокого риска наличия багов и отсутствия долгосрочной поддержки.

Функциональность в бета-версии

{{< feature-state state="beta" >}}

Результат:

FEATURE STATE: Kubernetes v1.17 beta

В настоящее время данная функциональность находится в состоянии beta, это означает, что:

Названия версий включают надпись “beta” (например, v2beta3).
Код хорошо протестирован. Активация этой функциональности — безопасно. Поэтому она включена по умолчанию.
Поддержка функциональности в целом не будет прекращена, хотя детали могут измениться.
Схема и/или семантика объектов может стать несовместимой с более поздними бета-версиями или стабильными выпусками. Когда это случится, мы даим инструкции по миграции на следующую версию. Это обновление может включать удаление, редактирование и повторного создание API-объектов. Этот процесс может потребовать тщательного анализа. Кроме этого, он может привести к простою приложений, которые используют данную функциональность.
Рекомендуется только для неосновного производственного использования из-за риска возникновения возможных несовместимых изменений с будущими версиями. Если у вас есть несколько кластеров, которые возможно обновить независимо, вы можете снять это ограничение.
Пожалуйста, попробуйте в действии бета-версии функциональности и поделитесь своими впечатлениями! После того, как функциональность выйдет из бета-версии, нам может быть нецелесообразно что-то дальше изменять.

Функциональность в стабильной версии

{{< feature-state state="stable" >}}

Результат:

FEATURE STATE: Kubernetes v1.17 stable

Данная функциональность является стабильной, это означает, что:

Версии именуются по шаблону vX, где X — это целое число.
Стабильные версии функциональности будут доступны во многих последующих выпусках.

Устаревшая функциональность

{{< feature-state state="deprecated" >}}

Результат:

FEATURE STATE: Kubernetes v1.17 deprecated

Данная функциональность объявлена устаревшей. Для получения дополнительной информации об этом состоянии перейдите на страницу Политика управления устаревшими версиями Kubernetes.

Глоссарий

Вы можете сослаться на термины из глоссария в виде всплывающей (при наведении мыши) подсказки, что удобно при чтении документации через интернет.

Исходные файлы терминов глоссария хранятся в отдельной директории по URL-адресу https://github.com/kubernetes/website/tree/master/content/en/docs/reference/glossary.

Демонстрация глоссария

Например, следующий фрагмент кода в Markdown будет отображен в виде всплывающей подсказки — clusterНабор машин, так называемые узлы, которые запускают контейнеризированные приложения. Кластер имеет как минимум один рабочий узел. :

{{< glossary_tooltip text="cluster" term_id="cluster" >}}

Заголовки таблиц

Для улучшения доступности таблиц для программ для чтения с экрана, добавьте заголовок к таблице. Чтобы добавить заголовок таблицы, поместите таблицу в макрокод table и определите значение заголовка в параметреcaption.

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

Пример:

{{< table caption="Конфигурационные параметры" >}}
Параметр | Описание | Значение по умолчанию
:---------|:------------|:-------
`timeout` | Тайм-аут для запросов | `30s`
`logLevel` | Уровень логирования | `INFO`
{{< /table >}}

Результат:

{{< table caption=“Конфигурационные параметры” >}} Параметр | Описание | Значение по умолчанию :———|:————|:——- timeout | Тайм-аут для запросов | 30s logLevel | Уровень логирования | INFO {{< /table >}}

Если вы изучите HTML-код таблицы, вы заметите следующий ниже элемент сразу после открывающего элемента <table>:

<caption style="display: none;"></caption>

Вкладки

Страница в формате Markdown (файл с расширением .md) на этом сайте может содержать набор вкладок для отображения нескольких разновидностей определённого решения.

Макрокод tabs принимает следующие параметры:

name: имя, отображаемое на вкладке.
codelang: если вы указываете встроенный контент для макрокода tab, вы можете сообщить Hugo, какой язык использовать для подсветки синтаксиса.
include: включаемый файл в вкладку. Если вкладка находится в узле пакета (leaf bundle) Hugo, то файл (может быть любым MIME-типом, который поддерживает Hugo) ищется в самом пакете. Если нет, то включаемое содержимое ищется относительно текущей страницы. Обратите внимание, что при использовании include вам следует использовать самозакрывающийся синтаксис. Например, {{</* tab name=“Content File #1” include=“example1” />}}. Язык может быть указан в codelang, в противном случае язык определяется из имени файла.
Если содержимое вкладки это Markdown, вам нужно использовать символ %. Например, {{% tab name="Вкладка 1" %}}This is **markdown**{{% /tab %}}
Вы можете совместно использовать перечисленные выше параметры. Ниже приведена демонстрация шорткода вкладок.

Ниже приведены примеры вкладок.

Заметка: Имя вкладки в элементе tabs должно быть уникальным на странице.

Демонстрация вкладок: подсветка синтаксиса в блоках кода

{{< tabs name="tab_with_code" >}}
{{{< tab name="Вкладка 1" codelang="bash" >}}
echo "Это вкладка 1."
{{< /tab >}}
{{< tab name="Вкладка 2" codelang="go" >}}
println "Это вкладка 2."
{{< /tab >}}}
{{< /tabs >}}

Результат:

Вкладка 1
Вкладка 2


echo "Это вкладка 1."


println "Это вкладка 2."

Демонстрация вкладок: встроенный Markdown и HTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
Это **разметка Markdown.**
{{< note >}}
Также можно использовать макрокоды.
{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
	<h3>Обычный HTML</h3>
	<p>Это <i>обычный</i> HTML.</p>
</div>
{{< /tab >}}
{{< /tabs >}}

Результат:

Markdown
HTML

Это разметка Markdown.

Заметка: Также можно использовать макрокоды.

Обычный HTML

Это обычный HTML.

Демонстрация вкладок: включение файлов

{{< tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}}
{{< /tabs >}}

Результат:

Content File #1
Content File #2
JSON File

Это пример содержимого в файле внутри пакета узла includes.

Заметка: Подключаемые файлы также могут содержать макрокоды.

Это другой пример содержимого в файле внутри пакета узла includes.

  {
    "apiVersion": "v1",
    "kind": "PodTemplate",
    "metadata": {
      "name": "nginx"
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "nginx"
        },
        "generateName": "nginx-"
      },
      "spec": {
         "containers": [{
           "name": "nginx",
           "image": "dockerfile/nginx",
           "ports": [{"containerPort": 80}]
         }]
      }
    }
  }

Что дальше

Подробнее про Hugo.
Подробнее про написание новой темы.
Подробнее про использование шаблонов страниц.
Подробнее про создание пулреквеста.

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

Была ли эта страница полезной?

Спасибо за отзыв! Если у вас есть конкретный вопрос об использовании Kubernetes, спрашивайте Stack Overflow. Сообщите о проблеме в репозитории GitHub, если вы хотите сообщить о проблеме или предложить улучшение.

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

Пользовательские макрокоды Hugo

Состояние функциональности

Демонстрация состояния функциональности

Код состояния функциональности

Функциональность в альфа-версии

Функциональность в бета-версии

Функциональность в стабильной версии

Устаревшая функциональность

Глоссарий

Демонстрация глоссария

Заголовки таблиц

Вкладки

Демонстрация вкладок: подсветка синтаксиса в блоках кода

Демонстрация вкладок: встроенный Markdown и HTML

Обычный HTML

Демонстрация вкладок: включение файлов

Что дальше

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