Введение

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. Первый!

Их использование интуитивно понятно: нумерация понадобится Вам при необходимости пронумеровать список (пошаговые инструкции). В случае же перечисления без какой-либо структуры, используйте список без нумерации.

По текущему стандарту списки должны заканчиваться точкой, точкой с запятой или другими знаками окончания предложения.

Цитаты

Использование максимально простое:

>Очень Важная Цитата
>> Из **Очень** Важного Документа

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

Очень Важная Цитата

Из Очень Важного Документа

Инлайн

Инлайн -- еще один способ `выделить текст`.

Инлайн – еще один способ выделить текст. Выделение желтым достигается за счет обрамление текста символами <^>.

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

Как можно заметить, позволяет выделять отформатированный текст в различных комбинациях. Форматирование текста поддерживается инлайном, но его стоит осуществлять извне разметки:

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

Жирный и курсив.

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

Таблицы

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

| Таблицы | такжe | поддерживаются | 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

Пример команды от суперпользователя c аргументом 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. Стандартизация статтей является одним из наших приоритетов, поэтому несоблюдение стандартов может стать причиной отправки материала на дальнейшую доработку.

Ознакомившись с данным руководством вместе с Общим руководством, Вы получите базовую квалификацию для написания пользовательских материалов. А дальнейшее – дело опыта!