Використання шорткодів

Шорткоди Hugo — це спеціальні заповнювачі з певним синтаксисом, які ви можете додати до вашого контенту для створення динамічного вмісту, таких як вкладки, зображення та іконки, посилання на інші сторінки та спеціальні макети контенту.

Ця сторінка пояснює доступні шорткоди та як їх використовувати у вашому контенті.

Додавання зображень

Розмістіть файли з зображеннями в тій же теці, що й markdown файл, який їх використовує. Щоб полегшити локалізацію та покращити доступність, рекомендується використовувати формат SVG. Нижче наведено приклад шорткоду з необхідними полями для додавання зображення:

{{< image width="75%" ratio="45.34%"
    link="./<image.svg>"
    caption="<Підпис, що показується під зображенням>"
    >}}

Поля link та caption є обовʼязковими, але шорткод також підтримує додаткові поля, наприклад:

{{< image width="75%" ratio="45.34%"
    link="./<image.svg>"
    alt="<Альтернативний текст, який використовується екранними зчитувачами та коли зображення не завантажується>"
    title="<Текст, що зʼявляється при наведенні миші>"
    caption="<Підпис, що показується під зображенням>"
    >}}

Якщо ви не включите поле title, Hugo використовує текст, встановлений у caption. Якщо ви не включите поле alt, Hugo використовує текст у title або у caption, якщо title також не визначено.

Поле width встановлює розмір зображення відносно навколишнього тексту і має стандартне значення 100%.

Поле ratio встановлює висоту зображення відносно його ширини. Hugo обчислює це значення автоматично для файлів зображень у теці. Однак ви повинні обчислити його вручну для зовнішніх зображень. Встановіть значення ratio в ([висота зображення]/[ширина зображення]) * 100.

Додавання іконок

Ви можете вставити загальні іконки у ваш контент за допомогою наступного коду:

{{< warning_icon >}}
{{< idea_icon >}}
{{< checkmark_icon >}}
{{< cancel_icon >}}
{{< tip_icon >}}

Іконки показуються всередині тексту. Наприклад: , , , та .

Додавання посилань на інші сторінки

Документація Istio підтримує три типи посилань залежно від їх цільового призначення. Кожен тип використовує різний синтаксис для цього.

• Зовнішні посилання. Це посилання на сторінки за межами документації Istio або репозиторіїв GitHub Istio. Використовуйте стандартний синтаксис Markdown для включення URL. Використовуйте протокол HTTPS, коли ви посилаєтеся на файли в Інтернеті, наприклад:

  [Описовий текст для посилання](https://mysite/myfile.html)

• Відносні посилання. Ці посилання вказують на сторінки на тому ж рівні що і поточний файл або далі в ієрархії. Розпочніть шлях відносних посилань з крапки ., наприклад:

  [Це посилання на сторінку-сестру або дочірню сторінку](./sub-dir/child-page.html)

• Абсолютні посилання. Ці посилання вказують на сторінки поза ієрархією поточної сторінки, але в межах сайту Istio. Розпочніть шлях абсолютних посилань з косої риски /, наприклад:

  [Це посилання на сторінку розділу про](/about/page/)

Незалежно від типу, посилання не вказують на файл index.md з вмістом, а на теку, що його містить.

Додавання посилань на контент на GitHub

Існує кілька способів посилання на контент або файли на GitHub:

• {{< github_file >}} використовується для посилання на окремі файли на GitHub, такі як YAML файли. Цей шорткод створює посилання на https://raw.githubusercontent.com/istio/istio*, наприклад:

  [liveness]({{< github_file >}}/samples/health-check/liveness-command.yaml)

• {{< github_tree >}} використовується для посилання на дерево тек на GitHub. Цей шорткод створює посилання на https://github.com/istio/istio/tree*, наприклад:

  [httpbin]({{< github_tree >}}/samples/httpbin)

• {{< github_blob >}} використовується для посилання на файл в джерелах GitHub. Цей шорткод створює посилання на https://github.com/istio/istio/blob*, наприклад:

  [RawVM MySQL]({{< github_blob >}}/samples/rawvm/README.md)

Вищезгадані шорткоди створюють посилання на відповідну гілку в GitHub, залежно від гілки, на яку націлена документація. Щоб перевірити, яка гілка наразі націлена, ви можете використовувати шорткод {{< source_branch_name >}}, щоб отримати назву поточної гілки.

Інформація про версію

Щоб показати поточну версію Istio у вашому контенті, отримавши поточну версію з вебсайту, використовуйте наступні шорткоди:

• {{< istio_version >}}, який показується як 1.24
• {{< istio_full_version >}}, який показується як 1.24.3

Терміни глосарію

Коли ви вперше представляєте спеціалізований термін Istio на сторінці, додаткові критерії прийняття для внесків вимагають включення терміна в глосарій та маркування його першого використання за допомогою шорткоду {{< gloss >}}. Шорткод створює спеціальне відображення, яке запрошує читачів натиснути на термін, щоб отримати спливаюче вікно з визначенням. Наприклад:

Компонент Istio, який програмує {{<gloss>}}Envoy{{</gloss>}} проксі, відповідальний за відкриття сервісів, балансування навантаження та маршрутизацію.

відображається наступним чином:

Компонент Istio, який програмує Envoy проксі, відповідальний за відкриття сервісів, балансування навантаження та маршрутизацію.

Якщо ви використовуєте варіант терміна у вашому тексті, ви все ще можете використовувати цей шорткод, щоб включити спливаюче вікно з визначенням. Щоб вказати заміну, просто включіть запис глосарію всередині шорткоду. Наприклад:

HTTP підтримка {{<gloss envoy>}}Envoy{{</gloss>}} була розроблена перш за все як HTTP/2 мультиплексуючий проксі.

Відображається зі спливаючим вікном для запису глосарію envoy наступним чином:

HTTP підтримка Envoy була розроблена перш за все як HTTP/2 мультиплексуючий проксі.

Виклики

Щоб підкреслити блоки контенту, ви можете відформатувати їх як попередження, ідеї, поради або цитати. Усі виклики використовують дуже подібні шорткоди:

{{< warning >}}
Це важливе попередження
{{< /warning >}}

{{< idea >}}
Це чудова ідея
{{< /idea >}}

{{< tip >}}
Це корисна порада від експерта
{{< /tip >}}

{{< quote >}}
Це цитата з чогось
{{< /quote >}}

Шорткоди вище показуються наступним чином:

Використовуйте виклики економно. Кожен тип виклику має конкретну мету, і їх надмірне використання зменшує їх ефективність і призначення. Загалом, не слід включати більше одного виклику на файл контенту.

Використання шаблонного тексту

Щоб повторно використовувати контент, зберігаючи єдине джерело для нього, використовуйте шорткоди шаблонного тексту. Щоб вставити шаблонний текст у будь-який файл контенту, використовуйте шорткод boilerplate наступним чином:

{{< boilerplate example >}}

Цей шорткод включає наступний контент з Markdown файлу example.md у теці /content/uk/boilerplates/:

Це деякий шаблонний markdown текст.

Приклад вкладеного текстового блоку в шаблоні.

Цей приклад показує, що вам потрібно вказати імʼя Markdown файлу з контентом, який ви хочете вставити на поточному місці. Наявні шаблонні файли розташовані в теці /content/uk/boilerplates.

Використання вкладок

Щоб показати контент з кількома варіантами чи форматами, використовуйте набори вкладок та вкладки. Наприклад:

• Еквівалентні команди для різних платформ
• Еквівалентні приклади коду різними мовами
• Альтернативні конфігурації

Щоб вставити контент з вкладками, поєднайте шорткоди tabset і tabs, наприклад:

{{< tabset category-name="platform" >}}

{{< tab name="One" category-value="one" >}}
ONE
{{< /tab >}}

{{< tab name="Two" category-value="two" >}}
TWO
{{< /tab >}}

{{< tab name="Three" category-value="three" >}}
THREE
{{< /tab >}}

{{< /tabset >}}

Шорткоди вище створюють наступний результат:

Значення атрибута name кожної вкладки містить текст, який показується для вкладки. Всередині кожної вкладки ви можете мати звичайний контент Markdown, але вкладки мають обмеження.

Атрибути category-name і category-value є необовʼязковими та дозволяють зберігати вибрану вкладку під час повторних відвідувань сторінки. Наприклад, відвідувач вибирає вкладку, і його вибір автоматично зберігається з заданим іменем і значенням. Якщо декілька наборів вкладок використовують одне і те ж імʼя категорії та значення, їх вибір автоматично синхронізується між сторінками. Це особливо корисно, коли на сайті є багато наборів вкладок, які містять однакові типи форматів.

Наприклад, кілька наборів вкладок можуть надавати варіанти для GCP, BlueMix та AWS. Ви можете встановити значення атрибута category-name як environment і значення для атрибутів category-value як gcp, bluemix і aws. Тоді, коли читач вибирає вкладку на одній сторінці, його вибір автоматично буде збережено по всіх наборах вкладок на сайті.

Обмеження вкладок

Ви можете використовувати майже будь-який Markdown у вкладці, з наступними винятками:

• Заголовки. Заголовки у вкладці зʼявляються у змісті, але натискання на посилання у змісті не вибирає автоматично вкладку.

• Вкладені набори вкладок. Не вкладайте вкладки. Це призводить до жахливого досвіду читання і може спричинити значну плутанину.

Використання банерів і наліпок

Щоб рекламувати майбутні події або анонсувати щось нове, ви можете автоматично вставляти тимчасові банери та наліпки у згенерований сайт у відповідному порядку. Ми реалізували наступні шорткоди для промо:

• Наліпки з відліком часу: Вони показують, скільки часу залишилося до великої події. Наприклад: «37 днів до ServiceMeshCon 30 березня». Наліпки мають деякий візуальний вплив на читачів перед подією і повинні використовуватися помірковано.

• Банери: Вони показують помітне повідомлення читачам про значну подію, яка має відбутися, відбувається чи вже відбулася. Наприклад «Istio 1.5 випущено, завантажте його сьогодні!» або «Приєднуйтесь до нас на ServiceMeshCon 30 березня». Банери є повноекранними блоками, які показуються читачам під час події.

Щоб створити банери та наліпки, створюйте Markdown файли у теках events/banners або events/stickers. Створюйте один Markdown файл на подію з відповідними полями front-matter для контролю їхньої поведінки. Наступна таблиця пояснює доступні опції: