29.09.2022

Применение Markdown в комментариях к исходному коду и в генерируемой технической документации

Одним из самых "скучных", но важных моментов при работе с IT-проектом, является работа с различного рода сопроводительной технической документацией. Я думаю, многие сталкивались с проблемой трудности поддержки документации в актуальном состоянии.

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

Зачастую подобный контент не имеет сложного форматирования и поэтому не имеет смысла использовать сложные в использовании текстовые форматы. А вот что важно - так это простота освоения и применения. В таких случаях, я рекомендую обратить внимание на использование облегченного языка разметки Markdown для смыслового оформления вашего контента. Тех, кто так или иначе работает с сервисами GitHub, GitLab, StackOverflow и пр. - это не должно удивить, поскольку там Markdown уже давно используется для оформления контента.

Что такое Markdown и в чем его преимущества

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

Важным преимуществом Markdown является то, что при всей его простоте, он позволяет не отходить от контекста с которым вы работаете, а текст на нем легко читается и форматируется даже в самом простейшем текстовом редакторе (фанаты vi и vim наверно рукоплещут).

Существует несколько популярных спецификаций Markdown (например GitHub Flavored Markdown (GFM)), которые в базовом варианте схожи, но отличаются поддержкой расширенного функционала. За вами остается только выбрать подходящую вам спецификацию и функционал.

Ниже я представлю только некоторую часть синтаксиса Markdown (GFM), которая мною часто используется, чтобы в общих чертах показать простоту языка.

Синтаксис Markdown

Оформление простого текста

Простое оформление текста:

*Курсивный текст*
**Полужирный текст**
~~Перечеркнутый текст~~

HTML аналог: теги <i>, <b>, <strike>.

Заголовки

Заголовки помечаются символом # и представляют собой HTML-аналоги тегов h1, h2, h3, h4, h5, h6.

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

HTML-аналог: теги <h1>, <h2>, <h3>, <h4>, <h5>, <h6>.

Списки

Обычный список оформляется подобным образом

- Первый
- Второй

Числовой список оформляется так:

1. Первый
2. Второй

HTML-аналог: теги <ul> и <ol> совместно с тегом <li>.

Оформление программного кода

Однострочный код обычно оформляется так:

`console.log("…");`

Многострочный код оформляется простым 4-х пробельным отступом:

    const msg = "Hello World";
    console.log(msg);

Или более подходящий вид c тремя апострофами:

```
const msg = "Hello World";
console.log(msg);
```

В некоторых спецификациях (GFM и пр.) допускается уточнение языка, на котором написан код. Это дает не только полезную подсказку, но и позволяет при выводе сделать корректную подсветку синтаксиса.

``` javascript
const msg = "Hello World";
console.log(msg);
```

``` html
<html>
  <body>
    ...
  </body>
</html>
```

HTML-аналог: теги <code> и <pre>.

Горизонтальная линия

Горизонтальная линия может оформляться любым вариантом из нижепредставленных:

* * *
***
*****
- - -
-----

HTML-аналог: тег <hr>.

Ссылки

Ссылки могут оформляться множеством вариантов

[Это ссылка на сайт][https://example.com]

Краткий вариант ссылки:

<https://www.example.com>

Многие редакторы и трансляторы Markdown просто преобразуют любые URL, которые найдут, в ссылки.

HTML-аналог: тег <a>.

Изображения

Ссылки на изображения делаются так:

![Описание иображения][https://www.example.com/image1.jpg]

HTML-аналог: тег <img>.

Таблицы (стандарт GFM)

| id  | user    | age |
| --- | ------- | --- |
| 101 | Иванов  | 22  |
| 102 | Петров  | 33  |
| 103 | Сидоров | 44  |

HTML-аналог: тег <table>, совместно с структурными тегами <thead>, <tbody>, <tfoot>, <tr>, <th>, <td>.

Прочие возможности Markdown

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

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

Рассмотрение всех возможностей расширений Markdown выходит за рамки этой статьи, поскольку эти расширения активно развиваются и соответственно с актуальными их возможностями вам проще всего ознакомиться прямо на страницах этих спецификаций:

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

Применение Markdown в комментариях к исходному коду

Может показаться парадоксальным, но использование синтаксиса Markdown в комментариях к исходному коду, может добавить семантики в текст, а также улучшить форматирование при использовании генераторов документации, без серьезного ущерба к читаемости. Причем это вполне совместимо с теми же JSDoc, PHPDoc, JavaDoc и пр. и фактически расширяет их возможности.

В обычных комментариях, семантика Markdown также позволяет стандартизировать некоторые вещи, такие как например, акцент внимания на чем-то, выделяемом двойными звездочками.

const msg = "…"; // **Caution**, use only UTF-8. See https://example.com

В этом примере, даже без преобразования в HTML (где "Caution" будет выделено полужирным, а ссылка будет кликабельной), явно виден акцент на слове "Caution", как предупреждение об осторожности.

Заключение

Любое нестандартное использование Markdown в проектах конечно должно быть заранее согласовано, поскольку важно соблюдать общий стиль. Но если в работе появилась необходимость несложного форматирования (в т.ч. семантического) контента, то имеет смысл не изобретать велосипед и просто взять Markdown, который показал себя простым, удобным, расширяемым и проверенным временем решением, которое в определенное степени благодаря спецификациям стандартизировано. А любая стандартизация в проектах - это очень важный фактор, влияющий на качество конечного решения.