Форматирование Markdown

​

Конвейер

1. Преобразование Markdown в IR (markdownToIR) — обычный текст и диапазоны стилей (полужирный, курсив, зачёркнутый, код, блок кода, спойлер, цитата, заголовок 1-6), а также диапазоны ссылок. Смещения измеряются в кодовых единицах UTF-16, поэтому диапазоны стилей Signal напрямую соответствуют его API. Таблицы анализируются только тогда, когда канал включает один из режимов таблиц.
2. Разбиение IR на фрагменты (chunkMarkdownIR / renderMarkdownIRChunksWithinLimit)
   • разбиение выполняется по тексту IR перед формированием вывода, поэтому встроенные стили и ссылки разделяются по фрагментам, а не обрываются на границе.
3. Формирование вывода для каждого канала (renderMarkdownWithMarkers) — карта маркеров стилей преобразует диапазоны во встроенную разметку канала.

​

Пример IR

Привет, **мир**! См. [документацию](https://docs.openclaw.ai).

{
  "text": "Привет, мир! См. документацию.",
  "styles": [{ "start": 6, "end": 11, "style": "bold" }],
  "links": [{ "start": 19, "end": 23, "href": "https://docs.openclaw.ai" }]
}

​

Обработка таблиц

channels:
  discord:
    markdown:
      tables: code
    accounts:
      work:
        markdown:
          tables: off

​

Правила разбиения на фрагменты

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

​

Политика ссылок

• Slack: [label](url) -> <url|label>; URL без подписи остаются без изменений.
• Telegram: [label](url) -> <a href="url">label</a> (режим анализа HTML).
• Signal: [label](url) -> label (url), если подпись ещё не совпадает с URL.

​

Спойлеры

​

Добавление или обновление средства форматирования канала

1. Выполните анализ один раз с помощью markdownToIR(...), передав подходящие для канала параметры (autolink, headingStyle, blockquotePrefix, tableMode).
2. Сформируйте вывод с помощью renderMarkdownWithMarkers(...) и карты маркеров стилей (либо пользовательской логики диапазонов стилей для таких транспортов, как Signal).
3. Разбейте на фрагменты с помощью chunkMarkdownIR(...) или renderMarkdownIRChunksWithinLimit(...) перед формированием каждого фрагмента.
4. Подключите адаптер, чтобы новый механизм разбиения и средство формирования вывода вызывались из пути отправки исходящих сообщений.
5. Протестируйте с помощью тестов форматирования и теста исходящей доставки, если канал разбивает сообщения на фрагменты.

​

Распространённые ошибки

• Токены Slack в угловых скобках (<@U123>, <#C123>, <https://...>) должны сохраняться при экранировании; необработанный HTML по-прежнему необходимо безопасно экранировать.
• Для HTML в Telegram необходимо экранировать текст за пределами тегов, чтобы избежать повреждения разметки.
• Диапазоны стилей Signal используют смещения UTF-16, а не смещения по кодовым точкам.
• Сохраняйте завершающие переводы строк в ограждённых блоках кода, чтобы закрывающий маркер располагался на отдельной строке.

​

Связанные материалы