Разметка бота в MAX: два тега, которых нет в Markdown

Markdown или HTML — выбор за полем format

Текст нового сообщения, ответа на callback-кнопку или отредактированного поста бот передаёт одним и тем же объектом — NewMessageBody. У него есть поле text (до 4000 символов) и необязательное поле format, у которого всего два допустимых значения: "markdown" и "html". Документация формулирует это так:

Про само поле format объект NewMessageBody говорит отдельно:

Если поле не заполнить, текст уйдёт как есть — без разбора символов *, _ или тегов. Разметка начинает работать только тогда, когда бот сам объявляет её тип.

Два тега, которых нет в обычном Markdown

Курсив, жирный, зачёркнутый и ссылка в таблице документации выглядят ровно так, как их знает любой, кто хоть раз писал текст в Markdown: *emphasized*, **strong**, ~~strikethrough~~, [Inline URL](https://dev.max.ru/). А дальше платформа переходит на собственный синтаксис. Подчёркнутый текст оформляется парой плюсов: ++underline++. Выделенный — парой галочек: ^^выделенный^^. Ни один из этих двух знаков в обычном Markdown ничего не значит — их придумала сама MAX.

Забавная деталь нашлась не в синтаксисе, а в предпросмотре: чтобы показать, каким выделенный текст станет на вид, страница документации использует не современный <mark> (он приберёжен для HTML-режима), а тег <font color="red"> — тот самый, который спецификация HTML давно считает устаревшим.

Упоминание — это ссылка на несуществующий домен

Упомянуть пользователя в тексте бот тоже не может напрямую именем или числовым id в отдельном поле — только оформив обычную ссылку с необычным адресом. В Markdown это выглядит так: [Имя Фамилия](max://user/user_id), в HTML — так: <a href="max://user/user_id">Имя Фамилия</a>. Схема max:// не открывается в браузере — это служебный адрес, который понимает только сама платформа, а держит его та же синтаксическая конструкция, что и обычная ссылка на сайт.

Имя тоже нельзя взять произвольным — документация уточняет:

Моноширинный текст теряет переносы строк

Моноширинный текст в Markdown оформляется обратными кавычками — `code`. Обычно такой блок в текстовых форматах существует именно затем, чтобы сохранить исходные отступы и переносы: код, таблицы, вывод консоли. У MAX это правило перевёрнуто — рядом с тегом документация оставляет предупреждение:

То есть многострочный фрагмент кода, вставленный в моноширинный блок бота, на экране получателя схлопнется в одну строку. Для многострочных примеров в сообщении бота такой тег не подходит вовсе — разбивать их приходится обычным текстом.

Опечатка выдаёт себя: шесть уровней, а тег один

В Markdown заголовок — это одна решётка: # заголовок. В HTML-режиме документация обещает выбор из шести уровней — <h1>…<h6>, как в обычном HTML. Но в самой таблице вместо шести разных тегов перечислены только четыре, а два места заняты повтором:

Заметить опечатку в интерфейсе бота невозможно в принципе — документация тут же поясняет почему:

Раз все шесть уровней визуально неотличимы друг от друга, ошибка в перечне тегов не влияет ни на одного бота — она осталась бы незамеченной и в тексте этой самой таблицы, если бы её не читать посимвольно.

Кто на самом деле пользуется разметкой

Объектом NewMessageBody пользуются три метода API: отправка нового сообщения POST /messages, редактирование PUT /messages и ответ на callback-кнопку POST /answers. Но раздел про форматирование текста на страницах самих методов прямо раскрывают только две — POST и PUT /messages; страница POST /answers лишь ссылается на объект NewMessageBody, не пересказывая его поля.

Пользовательской справки MAX это не касается вовсе: ни слова «Markdown», ни слова «подчёркнутый» в её 192 статьях нет — она рассказывает о переписке, а не о том, как боты собирают текст. Вся разметка целиком — забота стороны, которая пишет код бота, будь то библиотека на Go или любая другая, независимо от того, как именно бот был создан.

Частые вопросы