Кратко

  • RFC 7763, информационный документ IETF от марта 2016 года, зарегистрировал text/markdown. Запись требует charset, а необязательный variant позволяет обозначить синтаксис, который имел в виду автор.
  • Значение variant служит подсказкой. Получатель вправе воспользоваться им или прочитать текст иначе. RFC 7764 описал ряд вариантов Markdown, включая Original, GFM, CommonMark и Pandoc.
  • IANA ведёт реестр типов данных и отдельный реестр вариантов Markdown. Официальное название помогает передаче намерения, но страницу создаёт конкретный парсер.

Успешная копия, испорченная страница

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

Представим перенос технической инструкции. В таблице перечислены действия и сроки. Файл скопирован побайтово; оператор показывает одинаковые хеши до и после. Новая программа выводит вместо столбцов строки с вертикальными чертами. Читателю приходится восстанавливать связи самому. Целостность носителя доказана, а целостность полезного документа — нет. Ошибка живёт в действии, которое происходит после передачи: в выборе грамматики.

Сопутствующий RFC 7764 зафиксировал историю расхождения. Он выводит Markdown из работы John Gruber и Aaron Swartz 2004 года и перечисляет Original, GFM, CommonMark, Pandoc и другие варианты. В описании GFM указаны таблицы, ограждённые блоки кода и автоматически распознаваемые адреса. Это рабочие правила. Один и тот же знак в разных правилах создаёт разные части страницы.

Что было написано на конверте

RFC 7763 первым делом дал семейству имя для протоколов: text/markdown. Почтовое сообщение или ответ сервера могли передать этот тип вместе с содержимым. Регистрация требует параметр charset: получатель должен правильно получить символы из байтов ещё до разбора разметки. Для данного типа RFC не устанавливает кодировку по умолчанию.

Дополнительный параметр variant отвечает на следующий вопрос. Заголовок Content-Type: text/markdown; charset=UTF-8; variant=Original сообщает об общем формате и о предполагаемой разновидности. Без variant программа получателя ориентируется на собственный контекст. При наличии параметра она получает подсказку, а не приказ. RFC разрешает следовать ей, оставляя решение за получателем.

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

Сведения о варианте легко потерять при другом способе хранения. RFC 7764 обсуждает передачу Markdown за пределы сред, где сохраняются тип данных и параметры. Отдельный файл .md хранит текст, но значение variant из прежнего заголовка может исчезнуть. RFC 7763 рекомендует сохранять такие параметры вместе с материалом. Архив, который хранит только исходник, может сохранить слова и утратить инструкцию по их чтению.

Два реестра и множество исполнителей

В реестре типов данных IANA стоит text/markdown. Реестр вариантов отдельно перечисляет Original, GFM, CommonMark, Pandoc и другие имена; запись вариантов проводится по принципу первого обращения. Общие идентификаторы позволяют системам точнее говорить о содержимом. Реестр не управляет кодом каждого редактора и не устанавливает ему новый парсер.

Руководителю миграции нужны два вида проверки. Сравнение хешей отвечает за доставку исходника. Сравнение готовых страниц отвечает за сохранение таблиц, ссылок, заголовков и блоков кода. Если источник прежний, а страница изменилась, следует назвать вариант, версию и программу, которая провела преобразование. Фраза «мы поддерживаем Markdown» без этих данных слишком широка для серьёзной коллекции.

Четыре официальных источника этого материала подтверждают правила и записи реестров. Датированные руководства, выпуски исходного кода или сохранённые ответы понадобились бы для выводов о внедрении конкретными сервисами. Уже установленный факт 2016 года точен: документ получил переносимое имя, а власть над его показом осталась на стороне получателя.