Пользовательские макрокоды Hugo
На этой странице объясняются пользовательские макрокоды Hugo, которые можно использовать в Markdown-файлах документации Kubernetes.
Узнать подробнее про макрокоды можно в документации Hugo.
Состояние функциональности
В Markdown странице (файл с расширением .md
) вы можете добавить макрокод, чтобы отобразить версию и состояние документированной функциональной возможности.
Демонстрация состояния функциональности
Ниже показан фрагмент кода для вывода состояния функциональности, который сообщает о функциональности в стабильной версии Kubernetes 1.10.
{{< feature-state for_k8s_version="v1.10" state="stable" >}}
Результат:
Kubernetes v1.10
stable
- Версии именуются по шаблону vX, где X — это целое число.
- Стабильные версии функциональности будут доступны во многих последующих выпусках.
Допустимые значения для state
:
- alpha
- beta
- deprecated
- stable
Код состояния функциональности
По умолчанию отображается версия Kubernetes, соответствующая версии страницы или сайта. Это значение можно переопределить, передав параметр макрокода for_k8s_version
.
{{< feature-state for_k8s_version="v1.10" state="stable" >}}
Результат:
Kubernetes v1.10
stable
- Версии именуются по шаблону vX, где X — это целое число.
- Стабильные версии функциональности будут доступны во многих последующих выпусках.
Функциональность в альфа-версии
{{< feature-state state="alpha" >}}
Результат:
Kubernetes v1.18
alpha
- Названия версий включают надпись “alpha” (например, v1alpha1).
- Могут быть баги. Работа с этой функциональностью может привести к ошибкам. Поэтому по умолчанию она отключена.
- Поддержка функциональности может быть прекращена в любое время без предупреждения.
- API может быть несовместим с более поздними версиями без предупреждения.
- Рекомендуется для использования только в тестировочных кластерах с коротким жизненным циклом из-за высокого риска наличия багов и отсутствия долгосрочной поддержки.
Функциональность в бета-версии
{{< feature-state state="beta" >}}
Результат:
Kubernetes v1.18
beta
- Названия версий включают надпись “beta” (например, v2beta3).
- Код хорошо протестирован. Активация этой функциональности — безопасно. Поэтому она включена по умолчанию.
- Поддержка функциональности в целом не будет прекращена, хотя детали могут измениться.
- Схема и/или семантика объектов может стать несовместимой с более поздними бета-версиями или стабильными выпусками. Когда это случится, мы даим инструкции по миграции на следующую версию. Это обновление может включать удаление, редактирование и повторного создание API-объектов. Этот процесс может потребовать тщательного анализа. Кроме этого, он может привести к простою приложений, которые используют данную функциональность.
- Рекомендуется только для неосновного производственного использования из-за риска возникновения возможных несовместимых изменений с будущими версиями. Если у вас есть несколько кластеров, которые возможно обновить независимо, вы можете снять это ограничение.
- Пожалуйста, попробуйте в действии бета-версии функциональности и поделитесь своими впечатлениями! После того, как функциональность выйдет из бета-версии, нам может быть нецелесообразно что-то дальше изменять.
Функциональность в стабильной версии
{{< feature-state state="stable" >}}
Результат:
Kubernetes v1.18
stable
- Версии именуются по шаблону vX, где X — это целое число.
- Стабильные версии функциональности будут доступны во многих последующих выпусках.
Устаревшая функциональность
{{< feature-state state="deprecated" >}}
Результат:
Kubernetes v1.18
deprecated
Глоссарий
Вы можете сослаться на термины из глоссария в виде всплывающей (при наведении мыши) подсказки, что удобно при чтении документации через интернет.
Исходные файлы терминов глоссария хранятся в отдельной директории по 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 >}}
Результат:
Демонстрация вкладок: встроенный 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
Это обычный 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 >}}
Результат:
Это пример содержимого в файле внутри пакета узла 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, если вы хотите сообщить о проблеме или предложить улучшение.