Пару дней назад разговорились с одним из коллег о документации. В частности, беседа зашла о подходе “документация как код” (или doc-as-code). Выяснилось, что он не знаком с языком Markdown. Было немного странно, ведь он же “компьютерщик”!

В общем, я рассказал ему о Markdown. И задумался, если честно.

Наверное, это неплохая идея для небольшой заметки.

Понимаю, что в сети информации по этой теме “хоть пруд пруди”. Тем не менее, в данной заметке представлена краткая информация о Markdown и шпаргалка по его базовому синтакису (не всему, а только той части, которую я использую наиболее часто).

Markdown - это язык разметки, который можно использовать для добавления элементов форматирования в текстовые документы.

Использование Markdown отличается от использования WYSIWYG (What You See Is What You Get) редакторов. Например, в Microsoft Word, Google Docs и других подобных редакторах, при нажатии кнопок для форматирования изменения видны сразу. В Markdown дело обстоит иначе. При создании файла в формате Markdown (.md) в текст добавляется синтаксис Markdown для форматирования этого самого текста.

Markdown очень популярен среди техписателей и инженеров, которые готовят документацию по своим продуктам. Использование Markdown в написании документации как раз является одним из признаков подхода “документация как код”.

Ниже приведу небольшую шпаргалку, которой я когда-то пользовался. Повторю, что в сети достаточно информации на эту тему. Но всё-таки добавлю материал, что называется “для себя”. Глядишь, кому-то тоже пригодится.

Абзацы

Абзацы создаются простым добавлением пустой строки между ними.

Пример первого абзаца текста.

Пример второго абзаца текста.

Пример третьего абзаца текста.

# - Заголовки

Заголовки создаются добавлением перед ними спецсимвола # (хэш/hash). Уровень заголовка опледеляется количеством “хэшей”.

# Заголовок первого уровня
## Заголовок второго уровня
### Заголовок третьего уровня

* - Курсив

Курсив создаётся “оборачиванием” слова или фразы спецсимволом * (звёздочка/снежинка).

*Курсив* оформляется вот *так*.

** - Полужирное начертание

Полужирное начертание создаётся “оборачиванием” слова или фразы двумя “звёздочками” - **.

**Полужирный** шрифт оформляется вот **так**.

- - Неупорядоченный список

Неупорядоченный (маркированный) список создаётся добавлением перед элементами списка -.

- Элемент списка 1
- Элемент списка 2
- Элемент списка 3

1. - Упорядоченный список

Упорядоченный (нумерованный) список создаётся добавлением перед элементами списка порядкового номера элемента с точкой.

1. Первый элемент списка
2. Второй элемент списка
3. Третий элемент списка

[]() - Cсылка

Cсылка создаётся следующим образом:

  • в квадратные скобки [] добавляется текст ссылки,

  • в круглые скобки () добавляется адрес ссылки.

[Техкомпод - подкаст технического коммуникатора](https://techcommpod.ru/)

![]() - Изображения

Изображения добавляются аналогично ссылкам с добавлением восклицательного знака ! перед квадратными скобками []:

  • в квадратные скобки [] добавляется алтернативный текст изображения,

  • в круглые скобки () добавляется адрес расположения изображения.

[Логотип компании](assets/logo.png)

\`` - Встроенный код

Встроенный код создаётся “оборачиванием” слова, фразы или же действительно части кода двумя обратными кавычками - ``:

Тег `<table>` является контейнером для элементов, определяющих содержимое таблицы.

\`` - Блок кода (с подсветкой синтаксиса)

Блок кода создаётся “оборачиванием” этого самого кода тремя обратными кавычками - ```. Также опционально можно добавить подсветку синстаксиса. Для этого требуется просто добавить название языка программирования или разметки после первых обратных кавычек:

    ```json
    {
    "year": 2023,
    "month": "November",
    "day": 8
    }
    ```

*** - Горизонтальный разделитель

Горизонтальный разделитель добавляется просто тремя “звёздочками” в отдельной строке:

***

Это разумеется не полное описание стинтаксиса Markdown, а лишь небольшой его части, которую я использую наиболее часто.