Сторінка тестування документації

Ця сторінка має дві мети:

• Показати, як документація Kubernetes використовує Markdown
• Надати документ "тестування", який можна використовувати для перевірки змін в HTML, CSS та шаблонах, що впливають на загальну документацію.

Рівні заголовків

Вищезазначений заголовок є H2. Заголовок сторінки відображається як H1. Наступні секції показують H3-H6.

H3

Заголовок H3.

H4

Заголовок H4.

H5

Заголовок H5.

H6

Заголовок H6.

Вбудовані елементи

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

Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Стилі тексту в рядку

• жирний
• курсив
• жирний курсив
• перекреслений
• підкреслений
• підкреслений курсив
• підкреслений жирний
• підкреслений жирний курсив
• моноширинний текст
• моноширинний жирний

Списки

Markdown не має строгих правил обробки списків. Коли ми перейшли з Jekyll на Hugo, деякі списки були зламані. Щоб їх виправити, слід памʼятати про наступне:

• Переконайтеся, що ви відступаєте елементи підсписку на 2 пробіли.

• Щоб закінчити один список і почати інший, потрібно вставити HTML-коментар на новому рядку між списками, вирівняний з лівим краєм. Перший список інакше не закінчиться, незалежно від кількості порожніх рядків між ним і другим.

Списки з маркерами

• Це елемент списку.

• Це інший елемент списку в тому ж списку.

• Можна поєднувати - і *.
  • Щоб зробити піделемент, відступіть на два пробіли.
    • Це підпункт. Відступіть ще на два пробіли.
  • Ще один піделемент.

• Це новий список. З Hugo потрібно використовувати HTML-коментар для розділення двох послідовних списків. HTML-коментар повинен бути на лівому краю.

• Списки з маркерами можуть містити абзаци або блочні елементи.

  Відступіть вміст так, щоб він був на тому ж рівні, що й перший рядок маркера. Цей абзац і рядок блоку коду вирівнюються з першою B в Bullet вище.

  ls -l
  

  • І підсписок після деякого блочного контенту

• Елемент списку з маркерами може містити нумерований список.

  1. Нумерований піделемент 1
  2. Нумерований піделемент 2

Нумеровані списки

1. Це елемент списку
2. Це інший елемент списку в тому ж списку. Номер, який ви використовуєте в Markdown, не обовʼязково корелює з номером у кінцевому результаті. За угодою, ми зберігаємо їх в синхронізації.

1. Це новий список. З Hugo потрібно використовувати HTML-коментар для розділення двох послідовних списків. HTML-коментар повинен бути на лівому краю.

2. Нумеровані списки можуть містити абзаци або блочні елементи.

   Відступіть вміст так, щоб він був на тому ж рівні, що й перший рядок маркера. Цей абзац і рядок блоку коду вирівнюються з N у Numbered вище.

   ls -l
   

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

Вкладки

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

• Оберіть...
• Вкладка зі списком
• Nested headers

echo 'Списки вкладок можуть містити блоки коду!'

Списки перевірки

Списки перевірки технічно є списками з маркерами, але маркери приховані за допомогою CSS.

• Це елемент списку перевірки
• Це вибраний елемент списку перевірки

Блоки коду

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

це блок коду, створений зворотними косими апострофами

Метод зворотних косих апострофів має деякі переваги.

• Працює майже завжди
• Компактніший при перегляді вихідного коду
• Дозволяє вказати, якою мовою написаний блок коду, для підсвічування синтаксису
• Має чіткий кінець. Іноді метод відступу не працює з мовами, де пробіли мають значення, такими як Python або YAML.

Щоб вказати мову для блоку коду, помістіть її безпосередньо після першої групи зворотних косих апострофів:

ls -l

Звичайні мови, що використовуються в блоках коду документації Kubernetes, включають:

• bash / shell (обидві працюють однаково)
• go
• json
• yaml
• xml
• none (відключає підсвічування синтаксису для блоку)

Блоки коду, що містять shortcodes Hugo

Щоб показати сирі shortcodes Hugo, як у наведеному вище прикладі, і запобігти їх інтерпретації Hugo, використовуйте коментарі в стилі C безпосередньо після < і перед > символами. Наступний приклад ілюструє це (перегляньте вихідний код Markdown для цієї сторінки).

{{< alert color="warning" >}}Це попередження.{{< /alert >}}

Посилання

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

• [Посилання на Kubernetes.io](https://kubernetes.io/) або
• [Відносне посилання на Kubernetes.io](/)

Ви також можете використовувати HTML, але це не рекомендується. Наприклад, <a href="https://kubernetes.io/">Посилання на Kubernetes.io</a>.

Зображення

Щоб відформатувати зображення, використовуйте аналогічний синтаксис до посилань, але додайте перед зображенням символ !. У квадратних дужках міститься альтернативний текст зображення. Намагайтеся завжди використовувати альтернативний текст, щоб люди, які користуються читачами екрану, могли отримати користь від зображення.

Щоб вказати додаткові атрибути, такі як ширина, заголовок, підпис тощо, використовуйте figure shortcode, що є переважним у порівнянні з використанням HTML <img> теґу. Якщо ви хочете, щоб зображення також було гіперпосиланням, використовуйте атрибут link, замість того щоб обгортати все зображення в синтаксисі посилання Markdown, як показано нижче.

Навіть якщо ви вирішите не використовувати figure shortcode, зображення може бути також посиланням. Цього разу іконка олівця посилається на вебсайт Kubernetes. Зовнішні квадратні дужки обгортають весь теґ зображення, а цільове посилання знаходиться в дужках в кінці.

Ви також можете використовувати HTML для зображень, але це не рекомендується.

Таблиці

Прості таблиці мають один рядок настроку, а стовпці розділені символами |. Заголовок відокремлюється від тіла комірками, що містять лише щонайменше три символи -. Для зручності обслуговування намагайтеся тримати всі роздільники комірок на одному рівні, навіть якщо потрібно використовувати додатковий простір.

Заголовок є необовʼязковим. Будь-який текст, розділений |, буде відображатися як таблиця.

Markdown таблиці мають труднощі з блочними елементами всередині комірок, такими як пункти списку, блоки коду або кілька параграфів. Для складних або дуже широких таблиць використовуйте HTML замість Markdown.

Візуалізації з Mermaid

Ви можете використовувати візуалізації Mermaid JS. Версія Mermaid JS вказана в /layouts/partials/head.html

{{< mermaid >}}
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
{{</ mermaid >}}

В результаті виходить:

{{< mermaid >}}
sequenceDiagram
    Alice ->> Bob: Hello Bob, how are you?
    Bob-->>John: How about you John?
    Bob--x Alice: I am good thanks!
    Bob-x John: I am good thanks!
    Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.

    Bob-->Alice: Checking with John...
    Alice->John: Yes... John, how are you?
{{</ mermaid >}}

В результаті виходить:

Ви можете переглянути більше прикладів в офіційній документації.

Бокові панелі та зауваження

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

Бокові панелі

Бокова панель відзначає текст візуально, але без візуальної виразності зауважень.

Це бокова панель.

Ви можете мати параграфи та блокові елементи всередині бокової панелі.

Ви навіть можете включати блоки коду.

sudo dmesg

Зауваження

Зауваження (примітки, попередження тощо) використовують shortcodes Hugo.

Включення

Щоб додати короткі коди до включень.

Вбудоване середовище Katacoda