md4c: рендеринг Markdown

Обзор

37.1 Позиция

md4c — парсер, соответствующий CommonMark: ни DOM, ни строковых аллокаций — разбор есть поток событий. Эта минимальность идеально ложится на скриптовый мир XServer: когда вход — недоверенное содержимое, отрендерить его в контролируемый HTML куда безопаснее, чем исполнять шаблоны (идея контролируемых блоков гл. 19). Два импортируемых символа (md_parse / md_html) — вся поверхность API.

37.2 Модель событийного потока

md_parse колбэчит в порядке документа: вход/выход блоков (DOC/P/LI/CODE/TABLE…), вход/выход span'ов (EM/STRONG/CODE_SPAN/LINK/IMG…) и куски текста. Структуру колбэков заполняют целиком — пустые указатели не проверяются (жёсткое отличие от большинства библиотек); ненулевой возврат любого колбэка прерывает разбор. Свои рендереры (извлечение выжимки, генерация оглавления, очистка до текста) строятся на этом слое.

static int enter_block(MD_BLOCKTYPE t, void* d, void* u)
{
    return 0;  /* продолжаем */
}
/* leave_block / enter_span / leave_span / text той же формы */
MD_PARSER tParser = { 0, NULL, enter_block, leave_block,
                      enter_span, leave_span, text_cb };
md_parse(sDoc, iLen, &tParser, &tCtx);

37.3 Одношаговый рендеринг

md_html несёт полный набор колбэков и рендерит Markdown в HTML-фрагмент, передавая его через ваш колбэк вывода — та же форма мысли, что у md_parse. Флаги включают диалекты: таблицы, зачёркивание, списки задач, вики-ссылки. Экранирование HTML включено по умолчанию (теги исходника экранируются) — ключевое умолчание, превращающее недоверенный вход в безопасный вывод.

37.4 Связка с шаблонами

Типовой конвейер: Markdown из запроса → md_html рендерит в буфер → переменной входит в контролируемый блок шаблона гл. 19. Поля документов храните как Markdown и рендерьте в момент запроса — удобство редактирования и безопасность вместе. Статические сайты документации рендерятся один раз на Init (дисциплина горячего кэша гл. 41).

37.5 Контракт

Частые ошибки

Упражнения