Вступ¶

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

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

Примітка про заголовки

Заголовки не є спеціальними символами форматування; скоріше це стандартний markdown синтаксис. Вони містять один заголовок першого рівня:

# Це перший рівень

і будь-яка кількість значень підзаголовків, рівні від 2 до 6:

## Заголовок рівня 2
 ### Заголовок рівня 3
 #### Заголовок рівня 4
 ##### Заголовок 5 рівня
 ###### Заголовок 6 рівня

Ключовим тут є те, що ви можете використовувати скільки завгодно заголовків із 2–6, але лише ОДИН заголовок рівня 1. Хоча документ відображатиметься правильно з кількома заголовками рівня 1, автоматично створений зміст документа, який з’являється праворуч, НЕ відображатиметься правильно (або іноді взагалі) із кількома заголовками. Майте це на увазі під час написання документів.

Застереження¶

Попередження — це спеціальні візуальні «коробки», які дозволяють привернути увагу до важливих фактів і виділити їх серед решти тексту. Існують наступні типи застережень:

тип	Опис
note "примітка"	відображає текст у синьому полі
abstract "анотація"	відображає світло-блакитне текстове поле
info "Інформація"	відображає синьо-зелене текстове поле
tip "Підказка"	відображає синьо-зелене текстове поле (значок трохи зеленіший)
success "Успіх"	відображає зелене текстове поле
question "Питання"	відображає світло-зелене текстове поле
warning "Важливо"	відображає помаранчеве текстове поле
failure "Невдача"	відображає світло-червоне текстове поле
danger "Небезпечно"	відображає червоне текстове поле
bug "Помилка"	відображає червоне текстове поле
example "Приклад"	відображає фіолетове текстове поле
quote "Цитата"	відображає сіре текстове поле
custom ₁	завжди відображає синє текстове поле
custom ₂	використовує спеціальну назву в іншому типі

Попередження необмежені, як зазначено в custom ₁ вище. Додайте спеціальний заголовок до будь-якого типу попередження, щоб отримати потрібний колір рамки для конкретного попередження, як зазначено в custom ₂ вище.

Застереження завжди вводиться таким чином:

!!! тип_застереження "Заголовок застереження якщо є"

    текст застереження

Основний текст застереження має бути з відступом на чотири (4) інтервали від початкового поля. Легко побачити, де це, тому що він завжди вишиковується під першою літерою типу застереження. Зайвий рядок між заголовком і основним текстом не з’являтиметься, але наша система перекладу (Crowdin) має працювати правильно.

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

Примітка

текст

анотація

текст

Інформація

текст

Підказка

текст

Успіх

текст

Питання

текст

Важливо

текст

Невдача

текст

Небезпечно

текст

Власний заголовок

Спеціальний ₁ типу. Тут ми використали "спеціальний" як наш тип попередження. Знову ж таки, це завжди відображатиметься синім кольором.

Власний заголовок

Спеціальний ₂ типу. Ми змінили тип попередження «попередження» за допомогою спеціального заголовка. Ось як це виглядає:

!!! warning "Власний заголовок"

Попередження, що розгортаються¶

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

Вміст попередження

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

Це виглядає так у вашому редакторі:

??? warning "Вміст попередження"

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

Вміст із вкладками в документі¶

Вміст із вкладками форматується подібно до попереджень. Замість трьох знаків оклику чи питання, він починається трьома знаками рівності. Усе форматування попередження (4 пробіли тощо) застосовується до цього вмісту. Наприклад, для документації може знадобитися інша процедура для іншої версії Rocky Linux. Якщо для версій використовується вміст із вкладками, останній випуск Rocky Linux має бути першим. На момент написання цієї статті це було 9.0:

9.08.6

Процедура для цього в 9.0

Процедура для цього в 8.6

У вашому редакторі це виглядатиме так:

=== "9,0"

     Процедура для цього в 9.0

=== "8,6"

     Процедура для цього в 8.6

Пам’ятайте, що все, що потрапляє всередину розділу, має продовжувати використовувати 4-пробілний відступ, доки розділ не буде завершено. Це дуже зручна функція!

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

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

1. Пункт 1

2. Пункт 2

3. Пункт 3

Пункт 1
Пункт 2
Пункт 3

Якщо вам потрібно додати блоки коду, кілька рядків або навіть абзаци тексту до нумерованого списку, тоді текст має бути з відступом із тими самими чотирма (4) пробілами, які використовуються в попередженнях.

Однак ви не можете використовувати очі, щоб вирівняти їх під пронумерованим пунктом, оскільки це один інтервал. Якщо ви користуєтеся хорошим редактором розміток, ви можете встановити значення табуляції на чотири (4), що спростить форматування всього.

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

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

Наприклад: це має відступ на чотири (4) пробіли та представляє новий абзац тексту. Крім того, ми додаємо блок коду. Він також має такі ж чотири (4) пробіли, як і наш абзац:
```
dnf update
```
Ось наш другий пункт у списку. Оскільки ми використали відступ (вище), він відображається з наступною послідовністю нумерації (іншими словами, 2), але якби ми ввели елемент 1 без відступу (у наступному абзаці та коді), тоді це відображалося б як елемент 1 знову, що не те, чого ми хочемо.

І ось як це виглядає як необроблений текст:

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

    Наприклад: це має відступ на чотири (4) пробіли та представляє новий абзац тексту. Крім того, ми додаємо блок коду. Він також має такі ж чотири (4) пробіли, як і наш абзац:

    ```


    dnf update
    ```

2. Ось наш другий пункт у списку. Оскільки ми використали відступ (вище), він відображається з наступною послідовністю нумерації (іншими словами, 2), але якби ми ввели елемент 1 без відступу (у наступному абзаці та коді), тоді це відображалося б як елемент 1 знову, що не те, чого ми хочемо.

Таблиці¶

Таблиці допомагають нам розмістити параметри команд або, як у наведеному вище випадку, типи попереджень та описи. Ось як було введено таблицю в розділі Попередження:

| тип | Опис |
|-----------|------------------------------------------ ----------------------|
| note "примітка" | відображає синє текстове поле |
| abstract "анотація" | відображає світло-блакитне текстове поле |
| info "інформація" | відображає синьо-зелене текстове поле |
| tip "підказка" | відображає синьо-зелене текстове поле (значок трохи зеленіший) |
| success "успіх" | відображає зелене текстове поле |
| question "питання" | відображає світло-зелене текстове поле |
| warning "Важливо" | відображає помаранчеве текстове поле |
| failure "невдача" | відображає світло-червоне текстове поле |
| danger "небезпека" | відображає червоне текстове поле |
| bug "помилка" | відображає червоне текстове поле |
| example" приклад" | відображає фіолетове текстове поле |
| quote "цитата" | відображає сіре текстове поле |
| спеціальний <sub>1</sub> | завжди відображає синє текстове поле |
| спеціальний <sub>2</sub> | використовує спеціальний заголовок в іншому типі |

Зауважте, що необов’язково розбивати кожен стовпець за розміром (як ми зробили в першій частині таблиці), але це, звичайно, легше читається у вихідному файлі розмітки. Це може заплутати, коли ви об’єднуєте елементи разом, просто розбиваючи стовпці вертикальною рискою «|» де б не було природного розриву, як ви можете бачити в останніх двох пунктах таблиці.

Блок з цитатою¶

Блоки цитат призначені для цитування тексту з інших джерел для включення у вашу документацію, але їх необов’язково використовувати таким чином. Деякі учасники використовують цитати замість таблиць, наприклад, щоб перелічити деякі параметри. Приклади блоків з цитатами у розмітці:

> **предмет** – опис цього предмета

> **інший предмет** – інший опис цього предмета

Додатковий «розривний» рядок необхідний, щоб рядки не йшли разом.

Під час відтворення сторінки це виглядає так:

елемент – опис цього елемента інший предмет – інший опис елемента

Вбудовані та блочні кодові блоки¶

Our approach to the use of code blocks is pretty simple. Якщо ваш код достатньо короткий, щоб ви могли (і хотіли) використати його у реченні, яке ви щойно бачили, використовуйте одинарні зворотні галочки `, наприклад:

Речення з `командою за вашим вибором`.

Будь-яка команда, яка не використовується всередині текстового абзацу (особливо довгі шматки коду з кількома рядками), має бути повним блоком коду, визначеним потрійними зворотними галочками `:

```bash
sudo dnf install the-kitchen-sink
```

Біт bash цього форматування є несуттєвим ідентифікатором коду, але може допомогти підсвічувати синтаксис. Звичайно, якщо ви демонструєте Python, PHP, Ruby, HTML, CSS або будь-який інший код, "bash" слід змінити на будь-яку мову, яку ви використовуєте. До речі, якщо вам потрібно показати блок коду в блоці коду, просто додайте ще одну зворотну галочку ` до батьківського блоку, ось так:

````markdown
```bash
sudo dnf install the-kitchen-sink
```
````

І так, блок коду, який ви щойно бачили, використовував п’ять зворотних галочок на початку та в кінці, щоб правильно відтворити його.

Клавіатура¶

Ще один спосіб додати якомога більше ясності вашим документам — це відобразити клавіші на клавіатурі, які потрібно вводити правильно. Це робиться за допомогою <kbd>key</kbd>. Наприклад, щоб показати, що вам потрібно натиснути клавішу виходу у вашому документі, ви б використали <kbd>ESC</kbd. Якщо вам потрібно вказати, що потрібно натиснути декілька клавіш, додайте між ними + так: <kbd>CTRL</kbd> + <kbd>F4</kbd>. Якщо клавіші потрібно натискати одночасно, додайте до своїх інструкцій «одночасно» або якусь подібну фразу. Ось приклад клавіатурної інструкції у вашому редакторі:

Інсталяція типу робочої станції (з графічним інтерфейсом) запускає цей інтерфейс на терміналі 1. Оскільки Linux є багатокористувацьким, можна підключити кількох користувачів кілька разів на різних **фізичних терміналах** (TTY) або **віртуальних терміналах** (PTS). Віртуальні термінали доступні в графічному середовищі. Користувач перемикається з одного фізичного терміналу на інший за допомогою <kbd>Alt</kbd> + <kbd>Fx</kbd> з командного рядка або за допомогою <kbd>CTRL</kbd> + <kbd>Alt</kbd> + <kbd>Fx</kbd>.

І ось як це відображається під час відображення:

Інсталяція типу робочої станції (з графічним інтерфейсом) запускає цей інтерфейс на терміналі 1. Оскільки Linux є багатокористувацьким, можна підключити кількох користувачів кілька разів на різних фізичних терміналах (TTY) або **віртуальних терміналах ** (PTS). Віртуальні термінали доступні в графічному середовищі. Користувач перемикається з одного фізичного терміналу на інший за допомогою Alt + Fx із командного рядка або за допомогою CTRL + Alt + Fx.

Верхній, нижній індекс та спеціальні символи¶

Верхній і нижній індекси не є звичайною розміткою, але підтримуються в документації Rocky Linux за допомогою тегів HTML, які використовуються з тією ж метою. Верхній індекс розміщує текст, введений між тегами, трохи вище стандартного тексту, тоді як нижній індекс розміщує текст трохи нижче. Верхній індекс є найпоширенішим із цих двох на письмі. Деякі спеціальні символи вже з’являються в верхньому індексі без додавання тегів, але ви також можете поєднати тег, щоб змінити орієнтацію цих символів, як показано на символі авторського права нижче. Ви можете використовувати верхній індекс, щоб:

представити порядкові числа, наприклад 1^st, 2^nd, 3^rd
символи авторського права та товарних знаків, наприклад ^©, ^TM або ™, ®
як позначення для посилань, наприклад this¹, this² і this³

Деякі спеціальні символи, наприклад © зазвичай не є верхнім індексом, тоді як інші, такі як ™, є.

Ось як все вищесказане виглядає у вашому markdown коді:

* представляють порядкові номери, наприклад 1<sup>st</sup>, 2<sup>nd</sup>, 3<sup>rd</sup>
* символи авторського права та товарних знаків, наприклад <sup>&copy;</sup>, <sup>TM</sup> або  &trade;, &reg;
* як позначення для посилань, наприклад this<sup>1</sup>, this<sup>2</sup> і це<sup>3</sup>

Деякі спеціальні символи, такі як &copy; зазвичай не є верхнім індексом, тоді як інші, такі як &trade;, є.

Як бачите, для примусового надрядкового коду ми можемо використовувати підтримувані теги HTML <sup></sup>.

Підрядковий індекс вводиться за допомогою тегів <sub></sub> і, як зазначалося раніше, _{не так часто} використовується на письмі.

Верхній індекс для літератури¶

Деякі з вас можуть відчувати потребу посилатися на зовнішні джерела під час написання документації. Якщо у вас є лише одне джерело, ви можете включити його у свій висновок як одне посилання, але якщо у вас є кілька¹, ви можете використовувати верхній індекс, щоб позначити їх у своєму тексті², а потім перелічіть їх у кінці документа. Зверніть увагу, що літературу слід розташовувати після розділу «Висновок».

Після завершення ви можете мати свої позначки в пронумерованому списку відповідно до верхнього індексу або ввести їх як посилання. Обидва приклади показано тут:

"How Multiples Are Used In Text" by Wordy W. McWords https://site1.com
"Using Superscript In Text" by Sam B. Supersecret https://site2.com

або

1 "How Multiples Are Used In Text" by Wordy W. McWords
2 "Using Superscript In Text" by Sam B. Supersecret

І ось як це все виглядає у вашому редакторі:

1. "How Multiples Are Used In Text" by Wordy W. McWords [https://site1.com](https://site1.com)
2. "Using Superscript In Text" by Sam B. Supersecret [https://site2.com](https://site2.com)

або

[1](https://site1.com) "How Multiples Are Used In Text" by Wordy W. McWords  
[2](https://site2.com) "Using Superscript In Text" by Sam B. Supersecret

Групування різних типів форматування¶

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

Примітка

Усе може стати трохи божевільним, коли ви групуєте речі. Як коли:

Ви додаєте пронумерований список опцій до попередження
Або ви додаєте нумерований список із кількома блоками коду:
```
dnf install some-great-package
```
Це також є в нумерованому списку з кількох абзаців.

Або у вас може бути пронумерований список із додатковим зауваженням:

Цей предмет є дуже важливим

Тут ми додаємо команду з клавіатури до елемента списку:

Натисніть ESC без особливої причини.
Але цей пункт є дуже важливим і містить кілька абзаців

І в середині це застереження:

Важливо

З кількома елементами в різних типах форматування все може стати трохи божевільним!

Поки ви стежите за магічними чотирма (4) пробілами для відступів і розділення цих елементів, вони відображатимуться логічно й саме так, як ви хочете. Іноді це важливо.

Ви навіть можете вставити таблицю або цитату (буквально будь-який тип елемента форматування) в іншу. Тут ми маємо пронумерований список, попередження, таблицю та деякі елементи блок-цитат, які об’єднані разом:

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

Якщо ви відчуваєте себе перевантаженими, подумайте про:

важливо: я думаю, що болить мозок!

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

тип	добова норма кофеїну
чай	зрештою це приведе вас туди
кава	для вибагливих смакових рецепторів
red bull	на смак жахливий, але він вас утримає!
гірська роса	над розкрученим

цукор, якщо кофеїн вам не подобається

потерпіть, якщо нічого не допомагає, зосередьтеся більше

Є більше прикладів, але наведене вище повинно показати, що все може бути вкладено всередину. Просто запам’ятайте чотири (4) магічних місця.

Ось як цей приклад виглядає у вашому редакторі:

Поки ви стежите за чарівними чотирма (4) пробілами для розділення цих предметів, вони відображатимуться логічно й саме так, як ви хочете. Іноді це важливо.

Ви навіть можете вставити таблицю або цитату (буквально будь-який тип елемента форматування) в іншу. Тут ми маємо пронумерований список, попередження, таблицю та деякі елементи блок-цитат, які об’єднані разом:

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

2. Якщо ви відчуваєте себе перевантаженими, подумайте про:

     !!! warning "важливо: я думаю, що болить мозок!"

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

        | тип | добова норма кофеїну |
         |-----------------|------------------------------ ---|
         | чай | зрештою це приведе вас туди |
         | кава | для вибагливих смакових рецепторів |
         |  red bull | на смак жахливий, але він вас утримає! |
         | гірська роса | над розкрученим |

         > **цукор**, якщо кофеїн вам не подобається

         > **потерпіть**, якщо нічого не допомагає, зосередьтеся більше

3. Є більше прикладів, але наведене вище повинно показати, що все може бути вкладено всередину. Просто запам’ятайте чотири (4) магічних місця.

Останній пункт – коментарі¶

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

Найкращий спосіб додати коментар до вашої розмітки – використовувати квадратні дужки «[]» навколо двох похилих рисок «//», за якими йде двокрапка та вміст. Це виглядало б так:

[//]: це коментар, який буде замінено пізніше

У коментарі має бути порожній рядок перед і після коментаря.

Більше читання¶

Rocky Linux документ про те, як зробити внесок
Докладніше про застереження
Коротка довідка щодо уцінки
Більше коротких довідників для Markdown

Висновок¶

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

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

Нарешті, щоб спростити форматування, подумайте про те, щоб змінити значення TAB редактора розмітки на чотири (4) пробіли.

Востаннє оновлено: September 15, 2023

Author: Steven Spencer

Contributors: tianci li, Ezequiel Bruni, Krista Burdine, Ganna Zhyrnova