Створення діаграм

Цей посібник показує, як створювати, редагувати та поширювати діаграмами за допомогою JavaScript бібліотеки Mermaid. Mermaid.js дозволяє створювати діаграми за допомогою простого синтаксису, подібного до Markdown, всередині Markdown-файлів. Ви також можете використовувати Mermaid для створення файлів зображень у форматі .svg або .png, які ви можете додати до документації.

Цільовою аудиторією цього посібника є будь-хто, хто бажає дізнатися про Mermaid та/або як створювати і додавати діаграми до документації Kubernetes.

На схемі 1 показані теми, які розглядаються в цьому розділі.

Схема 1. Теми, які розглядаються в цьому розділі

Все що вам треба для роботи з Mermaid це:

• Знання основ markdown.
• Користуватись онлайн редактором Mermaid.
• Користуватись Hugo shortcodes.
• Користуватись Hugo shortcode {{< figure >}}.
• Виконувати локальний перегляд в Hugo.
• Знати як брати участь у створенні нового контенту.

Чому слід використовувати діаграми в документації

Діаграми покращують ясність та сприйняття документації. Це має переваги як для користувачів, так і для контриб'юторів.

Переваги для користувачів включають:

• Приємне перше враження. Детальна текстова сторінка привітання може налякати користувачів, особливо новачків у Kubernetes.
• Швидке освоєння концепцій. Діаграма може допомогти користувачам зрозуміти ключові моменти складної теми. Ваша діаграма може слугувати візуальним навчальним посібником для занурення в деталі теми.
• Краще запамʼятовування. Для деяких легше запамʼятати зображення, ніж текст.

Переваги для учасників включають:

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

Вам слід враховувати вашу цільову аудиторію. Окрім досвідчених користувачів K8s, у вас буде багато новачків у Kubernetes. Навіть проста діаграма може допомогти новим користувачам засвоїти концепції Kubernetes. Вони стають впевненішими та більш схильними до подальшого дослідження Kubernetes та документації.

Mermaid

Mermaid — це бібліотека JavaScript з відкритим вихідним кодом, яка дозволяє створювати, редагувати та легко ділитися діаграмами, використовуючи простий синтаксис, схожий на Markdown, який використовується в файлах Markdown.

Нижче наведено особливості Mermaid:

• Простий синтаксис коду.
• Включає вебінструмент для кодування та перегляду ваших діаграм.
• Підтримує кілька форматів, включаючи діаграми процесів, станів та послідовностей.
• Легке співробітництво з колегами через URL-адресу для кожної діаграми.
• Широкий вибір форм, ліній, тем та стилів.

Переваги використання Mermaid:

• Немає потреби в спеціальних інструментах для створення діаграм.
• Відповідає поточному робочому процесу з використанням PR. Ви можете розглядати код Mermaid як просто текст Markdown, доданий у ваш PR.
• Простий інструмент створює прості діаграми. Не хочете витрачати час на створення надто складних і деталізованих зображень. Тримайте їх простими!

Mermaid надає простий, відкритий та прозорий метод для спільнот SIG для додавання, редагування та співпраці над діаграмами для нової чи наявної документації.

Онлайн редактор

Онлайн редактор Mermaid — це вебінструмент, який дозволяє створювати, редагувати та переглядати діаграми.

Нижче наведено функції редактора:

• Показує код Mermaid разом зі згенерованою діаграмою.
• Генерує URL для кожної збереженої діаграми. URL відображається в адресному рядку вашого оглядача. Ви можете поділитися URL з колегами, які можуть отримати доступ до діаграми та змінювати її.
• Можливість отримати файли .svg або .png.

Методи створення діаграм

На схемі 2 показано три способи створення та додавання діаграм.

Схема 2. Методи створення діаграм.

В тексті

На схемі 3 показано кроки для додавання діаграми за допомогою методу Inline.

Схема 3. Кроки метода inline

Ось перелік кроків, які слід виконати для додавання діаграми за допомогою методу Inline:

1. Створіть вашу діаграму за допомогою онлайн редактора.
2. Збережіть URL діаграми для подальшого доступу.
3. Скопіюйте код Mermaid у місце в вашому файлі .md туди, де ви хочете, щоб зʼявилася діаграма.
4. Додайте підпис під діаграмою, використовуючи текст Markdown.

Під час побудови Hugo виконується код Mermaid і перетворюється на діаграму.

Ось приклад фрагмента коду, що міститься у файлі .md:

---
title: My PR
---
Figure 17 shows a simple A to B process.
some markdown text
...
{{< mermaid >}} 
    graph TB
    A --> B
{{< /mermaid >}}

Figure 17. A to B
more text

Для отримання додаткової інформації про підписи до діаграм, дивіться Як використовувати підписи.

Нижче наведено переваги методу Inline:

• Використання онлайн редактора.
• Легко копіювати код Mermaid до та з онлайн редактора та вашого файлу .md.
• Відсутність необхідності окремої обробки файлів зображень .svg.
• Текст контенту, код діаграми та підпис до діаграми знаходяться в одному файлі .md.

Ви повинні використовувати локальний та Netlify попередній перегляд для перевірки правильного показу діаграми.

Mermaid+SVG

На схемі 4 показано кроки для додавання діаграми за допомогою методу Mermaid+SVG.

Схема 4. Кроки методу Mermaid+SVG

Нижче наведено кроки, які слід виконати для додавання діаграми за допомогою методу Mermaid+SVG:

1. Створіть діаграму за допомогою онлайн редактора.
2. Збережіть URL діаграми для подальшого доступу.
3. Згенеруйте файл зображення .svg для діаграми та завантажте його до відповідної теки images/.
4. Використовуйте shortcode {{< figure >}} для посилання на діаграму у файлі .md.
5. Додайте підпис за допомогою параметра caption у shortcode {{< figure >}}.

Наприклад, використовуйте онлайн редактор для створення діаграми з назвою boxnet. Збережіть URL діаграми для подальшого доступу. Згенеруйте та завантажте файл boxnet.svg до відповідної теки ../images/.

Використовуйте shortcode {{< figure >}} у файлі .md вашого PR, щоб посилатися на файл зображення .svg та додати підпис.

{{< figure src="/static/images/boxnet.svg" alt="Boxnet figure" class="diagram-large" caption="Figure 14. Boxnet caption" >}}

Для отримання додаткової інформації про підписи до діаграм дивіться Як використовувати підписи.

Ви повинні додати URL онлйн редактора як коментар у файлі зображення .svg, використовуючи текстовий редактор. Наприклад, ви б включили наступне на початку файлу зображення .svg:

<!-- Щоб переглянути або редагувати код Mermaid, використовуйте наступний URL: -->
<!-- https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb ... <продовження рядка URL> -->

Нижче наведено переваги методу Mermaid+SVG:

• Використання інструменту онлайн редактора.
• Інструмент онлайн редактора підтримує найсучасніший набір функцій Mermaid.
• Використання існуючих методів kubernetes/website для обробки файлів зображень .svg.
• Середовище не вимагає підтримки Mermaid.

Переконайтеся, що ваша діаграма правильно відображається, використовуючи локальний та Netlify попередній перегляд.

Зовнішні інструменти

На схемі 5 показано кроки, яких слід дотримуватися для додавання діаграми за допомогою зовнішнього інструменту.

Спочатку створіть діаграму за допомогою зовнішнього інструменту і збережіть її як файл зображення у форматі .svg або .png. Після цього виконайте ті самі кроки, що й у методі Mermaid+SVG для додавання файлів зображень у форматі .svg.

Схема 5. Кроки методу з використання зовнішнього інструменту

Нижче наведено кроки, які слід виконати для додавання діаграми за допомогою методу External Tool:

1. Використовуйте зовнішній інструмент для створення діаграми.
2. Збережіть координати діаграми для доступу інших учасників. Наприклад, ваш інструмент може надати посилання на зображення діаграми, або ви можете зберегти файл з вихідним кодом, такий як .xml, у публічному репозиторії для подальшого доступу інших учасників.
3. Згенеруйте та збережіть діаграму у вигляді файлу зображення .svg або .png. Завантажте цей файл у відповідну теку ../images/.
4. Використовуйте shortcode {{< figure >}} для посилання на діаграму у файлі .md.
5. Додайте підпис за допомогою параметра caption у shortcode {{< figure >}}.

Ось приклад використання shortcode {{< figure >}} для діаграми images/apple.svg:

{{< figure src="/static/images/apple.svg" alt="red-apple-figure" class="diagram-large" caption="Figure 9. A Big Red Apple" >}}

Якщо ваш зовнішній інструмент малювання дозволяє:

• Ви можете включати кілька логотипів .svg або .png, іконок та зображень у свою діаграму. Однак, переконайтеся, що ви дотримуєтеся авторських прав і дотримуєтесь керівництва Kubernetes щодо використання контенту третіх сторін.
• Ви повинні зберегти координати діаграми для подальшого доступу інших учасників. Наприклад, ваш інструмент може надати посилання на зображення діаграми, або ви можете зберегти файл з вихідним кодом, наприклад .xml, для доступу інших учасників.

Для отримання додаткової інформації про логотипи та зображення K8s і CNCF, зверніться до розділу CNCF Artwork.

Нижче наведено переваги методу External Tool:

• Учасники добре знайомі з зовнішнім інструментом.
• Діаграми потребують більше деталей, ніж може надати Mermaid.

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

Приклади

У цьому розділі показано декілька прикладів діаграм Mermaid.

Приклад 1 — Обмеження на поширення топології Podʼів

Схема 6 показує діаграму зі сторінки Обмеження на поширення топології Podʼів

Схема 6. Обмеження поширення топології Podʼів

Код:

graph TB
   subgraph "zoneB"
       n3(Node3)
       n4(Node4)
   end
   subgraph "zoneA"
       n1(Node1)
       n2(Node2)
   end
 
   classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000;
   classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff;
   classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5;
   class n1,n2,n3,n4 k8s;
   class zoneA,zoneB cluster;

Приклад 2 – Ingress

Схема 7 показує діаграму, що зʼявляється на сторінці Що таке Ingress.

Code block:

graph LR;
 client([client])-. Ingress-managed <br> load balancer .->ingress[Ingress];
 ingress-->|routing rule|service[Service];
 subgraph cluster
 ingress;
 service-->pod1[Pod];
 service-->pod2[Pod];
 end
 classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000;
 classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff;
 classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5;
 class ingress,service,pod1,pod2 k8s;
 class client plain;
 class cluster cluster;

Приклад 3 — Потік системи К8s

На схемі 8 зображено Mermaid-діаграму послідовності, яка показує системний потік між компонентами K8 для запуску контейнера.

Код:

%%{init:{"theme":"neutral"}}%%
sequenceDiagram
    actor me
    participant apiSrv as control plane<br><br>api-server
    participant etcd as control plane<br><br>etcd datastore
    participant cntrlMgr as control plane<br><br>controller<br>manager
    participant sched as control plane<br><br>scheduler
    participant kubelet as node<br><br>kubelet
    participant container as node<br><br>container<br>runtime
    me->>apiSrv: 1. kubectl create -f pod.yaml
    apiSrv-->>etcd: 2. save new state
    cntrlMgr->>apiSrv: 3. check for changes
    sched->>apiSrv: 4. watch for unassigned pods(s)
    apiSrv->>sched: 5. notify about pod w nodename=" "
    sched->>apiSrv: 6. assign pod to node
    apiSrv-->>etcd: 7. save new state
    kubelet->>apiSrv: 8. look for newly assigned pod(s)
    apiSrv->>kubelet: 9. bind pod to node
    kubelet->>container: 10. start container
    kubelet->>apiSrv: 11. update pod status
    apiSrv-->>etcd: 12. save new state

Ви можете стилізувати один або декілька елементів діаграми за допомогою CSS. Це досягається за допомогою двох типів операторів у коді Mermaid.

• classDef визначає клас атрибутів стилю.
• class визначає один або декілька елементів, до яких буде застосовано клас.

В коді до схеми 7 ви можете побачити приклад.

classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff; // визначає стиль для класу k8s
class ingress,service,pod1,pod2 k8s; // Клас k8s застосовується до елементів ingress, service, pod1 та pod2.

Ви можете включити один або декілька операторів classDef та class у вашу діаграму. Ви також можете використовувати офіційний шістнадцятковий код кольору K8s #326ce5 для компонентів K8s у вашій діаграмі.

Для отримання додаткової інформації про стилізацію та класи див. Mermaid Styling and classes docs.

Як використовувати підписи до діаграм

Підпис — це короткий опис діаграми. Підпис може містити назву або короткий опис діаграми. Підписи не замінюють пояснювальний текст у вашій документації, а радше слугують як "контекстний звʼязок" між цим текстом та вашою діаграмою.

Поєднання тексту та діаграми, повʼязаних разом за допомогою підпису, допомагає надати чітке уявлення про інформацію, яку ви хочете донести до користувача.

Без підписів ви змушуєте користувача шукати текст над або під діаграмою, щоб зрозуміти її значення. Це може викликати невдоволення користувача.

На схемі 9 показано три компоненти правильного використання підписів: діаграма, підпис до діаграми та посилання на діаграму в тексті.

Схема 9. Компоненти заголовків

Діаграма

Методи Mermaid+SVG та External Tool генерують файли зображень у форматі .svg.

Існує shortcode {{< figure >}} для діаграми, що знаходиться у файлі зображення .svg, збереженому в /images/docs/components-of-kubernetes.svg:

{{< figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Схема 4. Компоненти архітектури Kubernetes" >}}

Ви повинні передавати значення src, alt, class та caption у shortcode {{< figure >}}. Ви можете змінювати розмір діаграми, використовуючи класи diagram-large, diagram-medium та diagram-small.

Дивіться Методи створення діаграм для отримання додаткової інформації про різні методи створення діаграм.

Підпис до діаграми

Далі додайте підпис до діаграми.

Якщо ви використовуєте діаграму з файла зображення .svg, вам слід використовувати параметр caption shortcodeʼа {{< figure >}}.

{{< figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Схема 4. Компоненти архітектури Kubernetes" >}}

Якщо ви використовуєте діаграму, що є вбудованим кодом Mermaid, тоді слід використовувати текст Markdown.

Схема 4. Компоненти архітектури Kubernetes

Нижче наведено кілька аспектів, які слід враховувати при додаванні підписів до діаграм:

• Використовуйте shortcode {{< figure >}} для додавання підпису до діаграм, створених за допомогою методів Mermaid+SVG та External Tool.
• Використовуйте простий текст Markdown для додавання підпису до діаграм, створених за допомогою методу Inline.
• Перед підписом діаграми додайте Схема НОМЕР.. Ви повинні використовувати слово Схема, і номер повинен бути унікальним для кожної діаграми на вашій сторінці документації. Додайте крапку після номера.
• Додайте текст підпису діаграми після Схема НОМЕР. в тому ж рядку. Підпис повинен закінчуватися крапкою. Зберігайте текст підпису коротким.
• Розташовуйте підпис до діаграми ПІД вашою діаграмою.

Посилання на діаграму

Нарешті, ви можете додати посилання на діаграму. Воно використовується у вашому тексті та повинно передувати самій діаграмі. Це дозволяє користувачеві повʼязати ваш текст із відповідною діаграмою. Схема НОМЕР у вашому посиланні та підписі повинні співпадати.

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

Ось приклад посилання на діаграму:

Схема 10 зображує компоненти архітектури Kubernetes.
Панель управління ...

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

Повна картина

Схема 10 показує діаграму архітектури Kubernetes, яка включає діаграму, підпис до діаграми та посилання на діаграму. Shortcode {{< figure >}} показує діаграму, додає підпис і включає необовʼязковий параметр link, щоб ви могли мати гіперпосилання на діаграму. Посилання на діаграму знаходиться в цьому абзаці.

Ось shortcode {{< figure >}} для цієї діаграми:

{{< figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Схема 10. Архітектура Kubernetes." link="/docs/concepts/overview/components/" >}}

Поради

• Завжди використовуйте оналйн редактор для створення/редагування вашої діаграми.

• Завжди використовуйте локальний Hugo та попередній перегляд Netlify, щоб перевірити, як діаграма відображається в документації.

• Включайте джерела діаграм, такі як URL, місцезнаходження вихідного коду або вказуйте, що код є самодокументуючим.

• Завжди використовуйте підписи до діаграм.

• Дуже корисно включати зображення діаграми у форматі .svg або .png та/або вихідний код Mermaid у тікетах та PRs.

• Для методів Mermaid+SVG та External Tool використовуйте файли зображень .svg, оскільки вони залишаються чіткими при збільшенні діаграми.

• Найкраща практика для файлів .svg — завантажити їх в інструмент для редагування SVG та використати функцію "Конвертувати текст у криві". Це гарантує, що діаграма відображатиметься однаково на всіх системах, незалежно від доступності шрифтів і підтримки рендерингу шрифтів.

• Mermaid не підтримує додаткові іконки або зображень.

• Shortcodes Hugo Mermaid не працюють в оналайн редакторі.

• Кожного разу, коли ви змінюєте діаграму в оналайн редакторі, ви повинні зберегти її, щоб згенерувати новий URL для діаграми.

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

• Перегляньте вихідний код цієї сторінки, diagram-guide.md, для отримання додаткових прикладів.

• Ознайомтеся з документацією Mermaid, щоб отримати пояснення та приклади.

Найважливіше — Робіть діаграми простими. Це заощадить час вам і вашим колегам-учасникам, а також полегшить читання для нових та досвідчених користувачів.