Вступ

Markdown – це легка мова розмітки, яку можна використовувати для додавання елементів форматування до текстових документів. Саме Markdown із невеликими власними модифікаціями використовується командною TheHost для написання наших матеріалів.

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

Ми будемо використовувати нові та нові елементи Markdown, визначення та стандарт використання яких ми опишемо у міру ознайомлення з матеріалом.

Основи Markdown

Заголовки

Markdown підтримує використання кількох рівнів заголовків. Стандарт TheHost використовує два з них - H2 та H3, якими відзначаються теми та підтеми матеріалу відповідно.

Виглядає їх використання так:

## Важлива основна тема
### Не менш важлива підтема №1
### Не менш важлива підтема №2
## Важлива основна тема, друга

Що трансформується у наступне:

Докладніше формування структури описано в Загальному Посібнику.

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

Форматування тексту

Markdown дозволяє використовувати _курсив_, **жирний**, __підкреслений__ і ~~перекреслений~~ текст.

Виглядає це так:

Markdown дозволяє використовувати курсив, жирний, підкреслений і перекреслений текст.

Однак, згідно з поточним стандартом TheHost, використовувати Вам доведеться в основному жирним формат тексту.

Жирним варто виділяти:

• Назви важливої для розуміння матеріалу інформації, наприклад кнопок, що використовуються в покроковій інструкції:

…у верхньому правому куті натисніть Повторити…

• Перша згадка власних назв або термінів, наприклад протоколу, про яку написаний матеріал:

SSH – криптографічний протокол…

• Як роздільник теми параграфів, які є частиною одного заголовка і чий поділ на окремі заголовки не є недоцільним:

для експорту, виконайте… Для імпорту, виконайте…

• Як виділення при використанні багатьох інших елементів, наприклад, колаутів (про які пізніше):

Рада: прочитайте цю статтю до кінця.

• Нумерація списків, наприклад у покрокових інструкціях:

1. Крок перший…

2. Крок другий…

• А також для виділення інших важливих словосполучень у статті за наявності такої крайньої необхідності:

У виділенні жирним головне - дотримуватися міри.

Списки

Згори ми використали елемент непронумованого списку. У Markdown він виглядає так:

* Перший.
* Другий.

Або ж, список може бути пронумерований:

1. Другий?
2. Перший!

Що на практиці виглядатиме так:

• Перший.
• Другий.

1. Другий?
2. Перший!

Їхнє використання інтуїтивно зрозуміле: нумерація знадобиться Вам за необхідності пронумерувати список (покрокові інструкції). У разі перерахування без будь-якої структури, використовуйте список без нумерації.

За поточним стандартом списки повинні закінчуватись точкою, крапкою з комою або іншими знаками закінчення пропозиції.

Цитати

Використання максимально просте:

>Дуже важлива цитата
>> З **Дуже** Важливого Документу

Цитати за поточним стандартом використовуються під час цитування, в основному пов’язане з юридичною інформацією або технічною документацією. Цитати підтримують вкладність та стандартне форматування, але використання обох не рекомендується:

Дуже важлива цитата

З Дуже Важливого Документу

Інлайн

Інлайн - ще один спосіб `виділити текст`.

Інлайн - ще один спосіб виділити текст`. Виділення жовтим досягається за рахунок обрамлення тексту символами <^>.

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

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

**`Жирний`** та _`курсив`_.

Жирний та курсив.

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

Таблиці

При необхідності детально описати створити таблицю з кількістю користувачів таблиць і колонок:

| Таблиці | також | підтримуються | Markdown | та | будуть | підлаштовуються | під | Розмір | сторінки |
|--------|-------|-------|-----------|--------|--- -----|----------|---------|--------|--------|
| кіль 1 | кільк 2 | кільк 3 | кільк 4 | кільк 5 | кільк 6 | кільк 7 | кільк 8 | кільк 9 | кіль 10 |
| кіль 1 | кільк 2 | кільк 3 | кільк 4 | кільк 5 | кільк 6 | кільк 7 | кільк 8 | кільк 9 | кіль 10 |
| кіль 1 | кільк 2 | кільк 3 | кільк 4 | кільк 5 | кільк 6 | кільк 7 | кільк 8 | кільк 9 | кіль 10 |
| кіль 1 | кільк 2 | кільк 3 | кільк 4 | кільк 5 | кільк 6 | кільк 7 | кільк 8 | кільк 9 | кіль 10 |
| кіль 1 | кільк 2 | кільк 3 | кільк 4 | кільк 5 | кільк 6 | кільк 7 | кільк 8 | кіль 9 | кіль 10 |

| Таблиці | також | підтримуються | Markdown | та | будуть | підлаштовуються | під | Розмір | сторінки | |--------|-------|-------|-----------|--------|— -----|----------|---------|--------|--------| | кіль 1 | кільк 2 | кільк 3 | кільк 4 | кільк 5 | кільк 6 | кільк 7 | кільк 8 | кільк 9 | кіль 10 | | кіль 1 | кільк 2 | кільк 3 | кільк 4 | кільк 5 | кільк 6 | кільк 7 | кільк 8 | кільк 9 | кіль 10 | | кіль 1 | кільк 2 | кільк 3 | кільк 4 | кільк 5 | кільк 6 | кільк 7 | кільк 8 | кільк 9 | кіль 10 | | кіль 1 | кільк 2 | кільк 3 | кільк 4 | кільк 5 | кільк 6 | кільк 7 | кільк 8 | кіль 9 | кіль 10 | | кіль 1 | кільк 2 | кільк 3 | кільк 4 | кільк 5 | кільк 6 | кільк 7 | кільк 8 | кільк 9 | кіль 10 |

Гіперпосилання

У Markdown гіперпосилання серед тексту створюються так:

[Текст](https://посилання)

Що в результаті перетворюється на Текст.

Посилання на статті нашої ж WIKI мають бути локалізовані. Якщо посилання веде за межі статті, хорошим тоном буде використовувати {target="_blank"} для відкриття посилання в новій вкладці, що перетворює існуючий формат на:

[Текст](https://посилання){target="_blank"}

Гіперпосилання можна і іноді нуно виділити: Текст.

Елементи Markdown

Зображення

Аналогічно Markdown підтримує зображення.

Достатньо на початку гіперпосилання поставити знак !:

![TheHost Logo](https://static.thehost.ua/ads/logo-308-111.png "Логотип **TheHost**")

Де:

• [TheHostLogo] - ця частина є їх описом, в першу чергу для пошукових систем.
• https://static.thehost.ua/ads/logo-308-111.png - безпосередньо посилання на зображення.
• Логотип **TheHost** – опис у вигляді охоплюючого зображення елемента.

І в результаті, має такий вигляд:

TheHost використовує аргумент {fancy} для можливості розгортання зображення на повний екран. Він опціональний і не підтримує спільне використання з елементом опису (‘Логотип TheHost’ у попередньому прикладі). Виглядає це так:

![TheHost Logo](https://static.thehost.ua/ads/logo-308-111.png){fancy}

Тепер, про стандарт використання:

• Ширина зображення не повинна перевищувати 1024 пікселі. Якщо все ж таки перевищення не уникнути - обов’язково використання аргументу {fancy}.
• Намагайтеся уникати зайве широких по відношенню до власної висоті зображень. Співвідношення розмірів 3:1 і більше не рекомендується до використання.
• Використані зображення повинні бути автентичними – не використовуйте знайдені в інтернеті зображення з невизначеним легальним статусом.
• За наявності будь-якої персональної інформації (такої, як IP-адреса Вашого сервера) - її рекомендується заблюрити з метою Вашої безпеки.

Нотатки

Колаути (англ. callouts) - використовуються як нотатки для виділення інформації. Використання покращують видимість і читаність статті.

<$>[note]
**Порада:** додаткова інформація, релевантна до теми, але не є її безпосередньою частиною.
<$>

<$>[warning]
**Попередження:** важлива та критична інформація, з якою читачеві обов'язково ознайомитись.
<$>

<$>[info]
**Інформація:** просунута інформація по темі, необов'язкова для ознайомлення для виконання поставленого матеріалом завдання.
<$>

<$>[draft]
**Нотатка/Характеристики:** перерахування характеристик/можливостей раніше певної сутності, а також використання як нотатки, яка не підходить для будь-якого з вищеописаних випадків.
<$>

На практиці:

Заголовок колауту обов’язково виділяється у форматі **Жирний:**, з двокрапкою наприкінці.

Колаути можуть бути скомбіновані з іншими елементами, але не з колаутами.

Cпойлер

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

[details Дуже важлива інформація
Багато дуже важливої інформації.
]

Спойлер складається з заголовка details з аргументами: closed - для закритого за замовчуванням, open - для відкритого за умовчанням. Без вказівки використовується closed.

Після чого йде заголовок спойлера та його наповнення.

І на практиці виглядає так:

Інформація: дуже важлива

Багато дуже важливої інформації.

Спойлери рекомендується комбінувати з колаутами, що відповідає тематиці інформації в спойлері. Наприклад:

<$>[info]
[details closed **Інформація:** не надто важлива, але дуже цікава
29 жовтня 1969 року відбувся перший сеанс зв'язку по **ARPANET** між Стенфордським та Каліфорнійським університетами – переговорники змогли передати на відстань 640 км повідомлення: `LOGIN`

Цей день вважається офіційною датою створення інтернету.
]
<$>

Що на практиці виглядає так:

Аналогічно колутам, заголовки спойлерів виділяються у форматі **Жирний:** заголовок, але крапка в кінці заголовка не потрібна. При цьому використання знака питання, якщо заголовок має форму запитання, допускається.

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

Кодовий блок

Кодові блоки існують виділення, власне, коду. Їхня підтримка формату тексту Markdown обмежена інлайном зі зрозумілих міркувань.

Також, кодові блоки підтримують безліч різних режимів розпізнавань розмітки, які можна вказати відразу після його оголошення за допомогою ```, наприклад ```nginx або ```js.

Приклад файлу конфігурації з міткою [label], яка дозволяє “дати ім’я” Вашому кодовому блоку:

server {
 listen 80 default_server;
 . . .
}

Зміст nginx визначає формат нижчого блоку. З повним списком підтримуваних форматів можна ознайомитися за посиланням.

У разі використання формату кодовий блок також буде забезпечений кнопкою Скопіювати:

const print = 'hello';
const ln = 'world';
console.log(print, ln);

Приклад виведення команди з додатковою міткою за допомогою [secondary_label]:

Висновок
Неможливо підключитися до MySQL на 127.0.0.1:3306: З'єднання відхилено

Приклад команди від імені звичайного користувача з аргументом command:

sudo apt-get update
sudo apt-get install apache2 -y

Приклад команди від суперкористувача з аргументом super_user:

adduser exampleuser
shutdown

Приклад команди з префіксом користувача:

FLUSH PRIVILEGES;
SELECT * FROM wp_posts;

Користувальницький префікс може містити пробіл:

FLUSH PRIVILEGES;
SELECT * FROM wp_posts;

За допомогою мітки [environment] кодові блоки можна змусити суттєво відрізнятися на вигляд. Це особливо корисно для матеріалів з виконанням дій на декількох серверах відразу (наприклад rsync):

ssh root@server_ip

echo "Другий сервер"

echo "Третій сервер"

echo "Четвертий сервер"

echo "П'ятий сервер"

І все це, за бажання, можна скомбінувати:

<html>
<body>
<head>
 <title>Мій заголовок</title>
</head>
<body>
 . . .
</body>
</html>

Висновок

Дотримання технічних стандартів з використання Markdown від TheHost значно скоротить час та покращить продуктивність при написанні матеріалів для нашої Wiki. Стандартизація статей є одним із наших пріоритетів, тому недотримання стандартів може стати причиною надсилання матеріалу на подальше доопрацювання.

Ознайомившись з даним посібником разом з Загальним посібником, Ви отримаєте базову кваліфікацію для написання користувацьких матеріалів. А подальше - справа досвіду!