Власні shortcodes Hugo
Ця сторінка пояснює, як використовувати shortcodes Hugo в документації Markdown для Kubernetes.
Детальніше про shortcodes можна дізнатися в документації Hugo.
Стан функції
На сторінці Markdown (.md
файл) на цьому сайті ви можете додати shortcodes для відображення версії та стану документованої функції.
Демонстрація стану функції
Нижче наведено демонстрацію фрагмента стану функції, який відображає функцію як стабільну в останній версії Kubernetes.
{{< feature-state state="stable" >}}
Показується як:
Kubernetes v1.32 [stable]
Дійсні значення для state
:
- alpha
- beta
- deprecated
- stable
Код стану функції
Показана версія Kubernetes типово є версією сторінки або сайту. Ви можете змінити версію стану функції, передавши параметр for_k8s_version
для shortcode. Наприклад:
{{< feature-state for_k8s_version="v1.10" state="beta" >}}
Показується як:
Kubernetes v1.10 [beta]
Отримання стану функції з файлу опису
Щоб динамічно визначити стан функції, використовуйте параметр feature_gate_name
. Деталі стану функції будуть витягнуті з відповідного файлу опису функціональних можливостей розташованого в content/en/docs/reference/command-line-tools-reference/feature-gates/
. Наприклад:
{{< feature-state feature_gate_name="NodeSwap" >}}
Показується як:
Kubernetes v1.30 [beta]
(стандартно увімкнено: true)Опис функціональних можливостей
На сторінці Markdown (.md
файл) на цьому сайті ви можете додати код для показу опису функціональної можливості.
Демонстрація опису функціональної можливості
Нижче наведено демонстрацію фрагмента опису функціональної можливості, який показує функцію як стабільну в останній версії Kubernetes.
{{< feature-gate-description name="DryRun" >}}
Показується як:
DryRun
: Вмикає запити dry rin на боці сервера, щоб можна було тестувати валідацію, злиття та мутацію без впровадження змін.
Глосарій
Існують два коротких коди для глосарія: glossary_tooltip
та glossary_definition
.
Ви можете посилатися на терміни глосарія з включенням, яке автоматично оновлюється і замінює вміст відповідними посиланнями з нашого глосарія. Коли вказівник миші знаходиться над терміном з глосарія, опис терміна з глосарія відобразиться у вигляді підказки. Термін глосарія також відображається як посилання.
Окрім включень з підказками, ви можете повторно використовувати визначення з глосарія у вмісті сторінки.
Дані для термінів глосарія зберігаються в теці глосарія, з файлом вмісту для кожного терміна глосарія.
Демонстрація глосарія
Наприклад, наступне включення в Markdown показується для терміна кластер з підказкою:
{{< glossary_tooltip text="cluster" term_id="cluster" >}}
Ось коротке визначення глосарія:
{{< glossary_definition prepend="Кластер — " term_id="cluster" length="short" >}}
яке показується як:
Кластер — набір робочих машин, що називаються вузлами, які виконують контейнеризовані застосунки. Кожен кластер має принаймні один робочий вузол.
Ви також можете включити повне визначення:
{{< glossary_definition term_id="cluster" length="all" >}}
яке показується як:
Набір робочих машин, що називаються вузлами, які виконують контейнеризовані застосунки. Кожен кластер має принаймні один робочий вузол.
Робочі вузли містять Podʼи, які є компонентами навантаження застосунку. Панель управління керує робочими вузлами та Podʼами в кластері. В операційних середовищах панель управління, зазвичай, працює на кількох компʼютерах, і кластер, як правило, має кілька вузлів, забезпечуючи стійкість до відмов та високу доступність.
Посилання на довідник API
Ви можете створити посилання на сторінку довідника API Kubernetes, використовуючи короткий код api-reference
, наприклад, на довідник
Pod:
{{< api-reference page="workload-resources/pod-v1" >}}
Вміст параметра page
є суфіксом URL сторінки довідника API.
Ви можете посилатися на конкретне місце на сторінці, вказавши параметр anchor
, наприклад, на довідник
PodSpec або розділ
environment-variables
сторінки:
{{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}}
{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}}
Ви можете змінити текст посилання, вказавши параметр text
, наприклад, посилаючись на
Змінні оточення
розділ сторінки:
{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Змінні оточення" >}}
Заголовки таблиць
Ви можете зробити таблиці більш доступними для екранних зчитувачів, додавши заголовок таблиці. Щоб додати заголовок до таблиці, оберніть таблицю кодом table
і вкажіть заголовок за допомогою параметра caption
.
Примітка:
Заголовки таблиць видимі для екранних зчитувачів, але невидимі при перегляді в стандартному HTML.Ось приклад:
{{< table caption="Configuration parameters" >}}
Parameter | Description | Default
:---------|:------------|:-------
`timeout` | The timeout for requests | `30s`
`logLevel` | The log level for log output | `INFO`
{{< /table >}}
Показується як:
Parameter | Description | Default |
---|---|---|
timeout | The timeout for requests | 30s |
logLevel | The log level for log output | INFO |
Якщо ви переглянете HTML для таблиці, ви повинні побачити цей елемент одразу
після відкриваючого елемента <table>
:
<caption style="display: none;">Configuration parameters</caption>
Вкладки
На сторінці Markdown (.md
файл) на цьому сайті ви можете додати набір вкладок для показу різних варіантів рішення.
Короткий код tabs
приймає такі параметри:
name
: Ім’я, яке відображається на вкладці.codelang
: Якщо ви надаєте внутрішній вміст для короткого кодуtab
, ви можете вказати Hugo, яку мову коду використовувати для підсвічування.include
: Файл для включення у вкладку. Якщо вкладка знаходиться в Hugo leaf bundle, файл, який може бути будь-якого MIME типу, підтримуваного Hugo, шукається у самому пакеті. Якщо ні, сторінка вмісту, яку потрібно включити, шукається відносно поточної сторінки. Зверніть увагу, що зinclude
у вас немає внутрішнього вмісту shortcode і ви повинні використовувати синтаксис самозакриваючих теґів. Наприклад,{{< tab name="Content File #1" include="example1" />}}
. Мову потрібно вказати уcodelang
, або мова буде визначена на основі імені файлу. Ффайли non-content стандартно підсвічуються як код.- Якщо ваш внутрішній вміст є Markdown, ви повинні використовувати роздільник
%
для оточення вкладки. Наприклад,{{% tab name="Tab 1" %}}This is **markdown**{{% /tab %}}
- Ви можете комбінувати зазначені вище варіації всередині набору вкладок.
Нижче наведено демонстрацію shortcode вкладок.
Примітка:
Ім’я вкладки вtabs
визначенні повинно бути унікальним на сторінці вмісту.Демонстрація вкладок: Підсвічування коду
{{< tabs name="tab_with_code" >}}
{{< tab name="Tab 1" codelang="bash" >}}
echo "This is tab 1."
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "This is tab 2."
{{< /tab >}}
{{< /tabs >}}
Показується як:
echo "This is tab 1."
println "This is tab 2."
Демонстрація вкладок: Вбудований Markdown та HTML
{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
This is **some markdown.**
{{< note >}}
It can even contain shortcodes.
{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
<h3>Plain HTML</h3>
<p>This is some <i>plain</i> HTML.</p>
</div>
{{< /tab >}}
{{< /tabs >}}
Показується як:
This is some markdown.
Примітка:
It can even contain shortcodes.Plain HTML
This is some plain 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 >}}
Показується як:
This is an example content file inside the includes leaf bundle.
Примітка:
Included content files can also contain shortcodes.This is another example content file inside the includes leaf bundle.
{
"apiVersion": "v1",
"kind": "PodTemplate",
"metadata": {
"name": "nginx"
},
"template": {
"metadata": {
"labels": {
"name": "nginx"
},
"generateName": "nginx-"
},
"spec": {
"containers": [{
"name": "nginx",
"image": "dockerfile/nginx",
"ports": [{"containerPort": 80}]
}]
}
}
}
Файли вихідного коду
Ви можете використовувати код {{% code_sample %}}
для вбудовування вмісту файлу в кодовий блок, щоб користувачі могли завантажити або скопіювати його вміст у буфер обміну. Цей код використовується, коли вміст зразкового файлу є загальним і багаторазовим, і ви хочете, щоб користувачі могли спробувати його самостійно.
Цей короткий код приймає два іменованих параметри: language
та file
. Обов’язковий параметр file
використовується для вказання шляху до файлу, який відображається. Опційний параметр language
використовується для вказання мови програмування файлу. Якщо параметр language
не надано, код намагатиметься вгадати мову на основі розширення файлу.
Наприклад:
{{% code_sample language="yaml" file="application/deployment-scale.yaml" %}}
Вихідний результат:
apiVersion: apps/v1
kind: Deployment
metadata:
name: nginx-deployment
spec:
selector:
matchLabels:
app: nginx
replicas: 4 # Update the replicas from 2 to 4
template:
metadata:
labels:
app: nginx
spec:
containers:
- name: nginx
image: nginx:1.16.1
ports:
- containerPort: 80
Коли ви додаєте новий зразковий файл, наприклад YAML файл, створіть файл в одній з підтек <LANG>/examples/
, де <LANG>
— це мова для сторінки. У Markdown вашої сторінки використовуйте код code
:
{{% code_sample file="<RELATIVE-PATH>/example-yaml>" %}}
де <RELATIVE-PATH>
— шлях до зразкового файлу, який потрібно включити, відносно теки examples
. Наступний код посилається на YAML файл, розташований за адресою /content/en/examples/configmap/configmaps.yaml
.
{{% code_sample file="configmap/configmaps.yaml" %}}
Застарілий код {{% codenew %}}
замінюється на {{% code_sample %}}
. Використовуйте {{% code_sample %}}
(а не {{% codenew %}}
чи {{% code %}}
) у новій документації.
Маркер контенту третіх сторін
Для роботи з Kubernetes потрібно стороннє програмне забезпечення. Наприклад, вам зазвичай потрібно додати DNS-сервер до вашого кластера, щоб забезпечити правильну роботу розпізнавання імен.
Коли ми посилаємося на стороннє програмне забезпечення або згадуємо про нього, ми дотримуємося керівництва з контенту і також позначаємо ці сторонні елементи.
Використання цих shortcodes додає відмову від відповідальності до будь-якої сторінки документації, яка їх використовує.
Списки
Для списку кількох сторонніх елементів додайте:
{{% thirdparty-content %}}
відразу після заголовка розділу, що включає всі елементи.
Елементи
Якщо у вас є список, в якому більшість елементів належать до програмного забезпечення проєкту (наприклад: сам Kubernetes, і окремий компонент Descheduler), то є інша форма для використання.
Додайте короткий код:
{{% thirdparty-content single="true" %}}
перед елементом або відразу після заголовка для конкретного елемента.
Деталі
Ви можете відобразити HTML елемент <details>
за допомогою шорткоду:
{{< details summary="Детальніше про віджети" >}}
API розширення frobnicator реалізує _віджети_ із використанням тексту прикладу.
Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.
{{< /details >}}
Це буде показано так: API розширення frobnicator реалізує віджети із використанням тексту прикладу. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.Детальніше про віджети
Примітка:
Використовуйте цей шорткод помірно; зазвичай краще, коли весь текст показується читачам безпосередньо.Рядки версій
Щоб створити рядок версії для включення в документацію, ви можете вибрати з кількох shortcode для версії. Кожен код версії відображає рядок версії, отриманий зі значення параметра версії, знайденого у файлі конфігурації сайту, hugo.toml
. Два найбільш часто використовуваних параметри версії — це latest
і version
.
{{< param "version" >}}
Код {{< param "version" >}}
генерує значення поточної версії документації Kubernetes з параметра сайту version
. Код param
приймає назву одного параметра сайту, в цьому випадку: version
.
Примітка:
В раніше випущеній документації значення параметрівlatest
і version
не є еквівалентними. Після випуску нової версії, latest
інкрементується і значення version
для набору документації залишається незмінним. Наприклад, раніше випущена версія документації відображає version
як v1.19
і latest
як v1.20
.Показується як:
v1.32{{< latest-version >}}
Код {{< latest-version >}}
повертає значення параметра сайту latest
. Параметр сайту latest
оновлюється, коли випускається нова версія документації. Цей параметр не завжди відповідає значенню version
у наборі документації.
Показується як:
v1.32{{< latest-semver >}}
Короткий код {{< latest-semver >}}
генерує значення latest
без префікса "v".
Показується як:
1.32{{< version-check >}}
Код {{< version-check >}}
перевіряє, чи присутній параметр min-kubernetes-server-version
на сторінці, а потім використовує це значення для порівняння з version
.
Показується як:
Для перевірки версії введітьkubectl version
.{{< latest-release-notes >}}
Код {{< latest-release-notes >}}
генерує рядок версії з latest
і видаляє префікс "v". Короткий код друкує нове посилання на сторінку з нотатками про випуски з модифікованим рядком версії.
Показується як:
https://git.k8s.io/kubernetes/CHANGELOG/CHANGELOG-1.32.mdЩо далі
- Дізнайтеся про Hugo.
- Дізнайтеся про створення нової теми.
- Дізнайтеся про типи вмісту сторінок.
- Дізнайтеся про відкриття pull request.
- Дізнайтеся про розширений варіант участі.