Власні shortcodes Hugo

Ця сторінка пояснює, як використовувати shortcodes Hugo в документації Markdown для Kubernetes.

Детальніше про shortcodes можна дізнатися в документації Hugo.

Стан функції

На сторінці Markdown (.md файл) на цьому сайті ви можете додати shortcodes для відображення версії та стану документованої функції.

Демонстрація стану функції

Нижче наведено демонстрацію фрагмента стану функції, який відображає функцію як стабільну в останній версії Kubernetes.

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

Показується як:

Дійсні значення для state:

• alpha
• beta
• deprecated
• stable

Код стану функції

Показана версія Kubernetes типово є версією сторінки або сайту. Ви можете змінити версію стану функції, передавши параметр for_k8s_version для shortcode. Наприклад:

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

Показується як:

Отримання стану функції з файлу опису

Щоб динамічно визначити стан функції, використовуйте параметр feature_gate_name. Деталі стану функції будуть витягнуті з відповідного файлу опису функціональних можливостей розташованого в content/en/docs/reference/command-line-tools-reference/feature-gates/. Наприклад:

{{< feature-state feature_gate_name="NodeSwap" >}}

Показується як:

Опис функціональних можливостей

На сторінці 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.

Ось приклад:

{{< table caption="Configuration parameters" >}}
Parameter | Description | Default
:---------|:------------|:-------
`timeout` | The timeout for requests | `30s`
`logLevel` | The log level for log output | `INFO`
{{< /table >}}

Показується як:

Якщо ви переглянете 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 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 >}}

Показується як:

• Tab 1
• Tab 2

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 >}}

Показується як:

• Markdown
• 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

{
    "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" %}}

Вихідний результат:

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" %}}

перед елементом або відразу після заголовка для конкретного елемента.

Рядки версій

Щоб створити рядок версії для включення в документацію, ви можете вибрати з кількох shortcode для версії. Кожен код версії відображає рядок версії, отриманий зі значення параметра версії, знайденого у файлі конфігурації сайту, hugo.toml. Два найбільш часто використовуваних параметри версії — це latest і version.

{{< param "version" >}}

Код {{< param "version" >}} генерує значення поточної версії документації Kubernetes з параметра сайту version. Код param приймає назву одного параметра сайту, в цьому випадку: version.

Показується як:

{{< latest-version >}}

Код {{< latest-version >}} повертає значення параметра сайту latest. Параметр сайту latest оновлюється, коли випускається нова версія документації. Цей параметр не завжди відповідає значенню version у наборі документації.

Показується як:

{{< latest-semver >}}

Короткий код {{< latest-semver >}} генерує значення latest без префікса "v".

Показується як:

{{< version-check >}}

Код {{< version-check >}} перевіряє, чи присутній параметр min-kubernetes-server-version на сторінці, а потім використовує це значення для порівняння з version.

Показується як:

{{< latest-release-notes >}}

Код {{< latest-release-notes >}} генерує рядок версії з latest і видаляє префікс "v". Короткий код друкує нове посилання на сторінку з нотатками про випуски з модифікованим рядком версії.

Показується як:

Що далі

• Дізнайтеся про Hugo.
• Дізнайтеся про створення нової теми.
• Дізнайтеся про типи вмісту сторінок.
• Дізнайтеся про відкриття pull request.
• Дізнайтеся про розширений варіант участі.