Markdown в блоках

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

Как это устроено

1. Контентщик пишет текст в редакторе прямо в предпросмотре страницы.
2. Текст хранится как markdown в служебном поле блока _markdown.
3. Перед рендерингом markdown конвертируется в HTML.
4. Шаблон получает готовый HTML в корневой переменной content.

<section class="article article--{{ props.theme | default: 'light' }}">
  <div class="article__inner" style="max-width: {{ props.max_width | default: '800px' }}">
    {{ content }}
  </div>
</section>

Ключевые правила шаблона:

• content — без префикса props, это корневая переменная;
• внутри уже HTML: не экранировать, не оборачивать в <p>;
• поле контента не объявляется в схеме — оно системное;
• любые дополнительные настройки (тема, размер шрифта, ширина колонки) — обычные поля схемы, доступные как props.*.

Остальные переменные контекста — те же, что у любого блока, см. Что доступно в контексте.

CSS обязан покрывать все теги

Разметку внутри content пишете не вы, а контентщик — значит, появиться может любой тег. Блок без стилей на все элементы разъезжается на первой же вставленной таблице.

Минимальный набор, который стоит стилизовать:

Что	Теги
Заголовки	h1–h6
Текст	p, strong, em, code, a
Списки	ul, ol, li
Блоки	blockquote, pre, hr, img
Таблицы	table, thead, tbody, tr, th, td

Селекторы пишите от корневого класса блока, чтобы стили не текли на остальную страницу:

.article__inner h2 {
  font-size: 1.5rem;
  margin: 1.5em 0 0.5em;
}
.article__inner p {
  line-height: 1.7;
  margin: 0 0 1em;
}
.article__inner a {
  color: #2563eb;
  text-decoration: underline;
}

Таблицы приходят в обёртке

Каждая таблица оборачивается в контейнер с горизонтальной прокруткой, чтобы широкая таблица не растягивала страницу на мобильном:

<div class="pagecraft-wysiwyg-table-wrapper" style="width:100%;overflow-x:auto">
  <table>
    …
  </table>
</div>

Обёртка — часть контракта, она появляется и в предпросмотре, и на витрине. Учитывайте её в CSS и не задавайте таблице фиксированную ширину больше контейнера.

Синтаксис: что работает везде

Эти конструкции одинаково превращаются в HTML и в предпросмотре, и на опубликованной странице:

Синтаксис	Результат
# Заголовок … ###### Заголовок	h1–h6
**жирный**, *курсив*	strong, em
[текст](https://…)	a
	img
- пункт, 1. пункт	ul/ol + li
> цитата	blockquote
`код` и блок кода в тройных кавычках	code, pre > code
---	hr
таблица через |	table в скроллируемой обёртке
сырой HTML	проходит как есть

⚠️ Синтаксис, который расходится

Конвертеров два: в браузере — GitHub-совместимый, на сервере — строгий CommonMark с одним расширением на таблицы. Всё, что относится к GitHub-диалекту, в предпросмотре работает, а на витрине выводится как обычный текст.

Пишем	В предпросмотре	На опубликованной странице
~~зачёркнутый~~	<del>зачёркнутый</del>	текст вместе с тильдами, как написан
https://example.com без скобок	ссылка	обычный текст
- [ ] пункт, - [x] пункт	чекбоксы	текст [ ] пункт
[текст](javascript:…)	ссылка со скриптом	ссылка без href
текст[^1] (сноски)	не поддерживается	не поддерживается

Практическое правило: зачёркивание, чекбоксы и голые URL не использовать. Ссылку писать явно — [example.com](https://example.com).

Про остальные расхождения предпросмотра и публикации — Различия сервера и браузера.

Переносы строк

Одиночный перенос строки абзац не разрывает — это поведение CommonMark, и оно одинаково в обоих конвертерах. Новый абзац — пустая строка между блоками текста.

Когда markdown-блок не нужен

Задача	Чем делать
Заголовок, подзаголовок и кнопка	обычный блок со схемой полей
Повторяющиеся карточки	поле типа array в схеме
Товары, корзина, живые данные	блок со слотами, Биндинги и слоты
Статья, которую правит контентщик	markdown-блок

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

---

Источники: backend/src/Publishing/BlockRenderer.php (buildContext, convertMarkdown), front/src/lib/marked.ts, front/src/lib/placeholder.ts (assembleBlockHtml), front/src/components/BlockEditor/BlockPreview.tsx; поведение сверено прогоном обоих конвертеров (league/commonmark + TableExtension против marked).