Совместимость с YFM

КраткоКраткоКратко

База знаний Eventicious использует YFM (Yandex Flavored Markdown) как основной формат контента после интеграции @diplodoc/transform в Astro/Starlight. Страница фиксирует фактическую совместимость блоков и нужна как ориентир для авторов, редакторов и разработчиков, которые готовят новые материалы или мигрируют старые статьи.

Когда использоватьКогда использоватьКогда использовать

Используйте YFM-совместимый .md в следующих случаях:

• Публикация новых статей, справок и инструкций в базе знаний.
• Материалы, которые будут обрабатываться редактором или LLM-rewrite пайплайном.
• Контент, который должен стабильно рендериться без дополнительной поддержки компонентов.

Используйте .mdx только когда странице действительно нужны встроенные Astro- или Starlight-компоненты. В остальных случаях оставайтесь на .md, чтобы не выходить за границы поддерживаемого контура.

Что уже поддерживаетсяЧто уже поддерживаетсяЧто уже поддерживается

Без отдельной доработки работают:

• Заголовки, абзацы, списки и ссылки.
• Таблицы.
• Fenced code blocks.
• Изображения по абсолютным URL и из директории public/.
• Блок заметки: {% note %} / {% endnote %}.
• Блок скрытого контента: {% cut %} / {% endcut %}.
• Список вкладок: {% list tabs %} / {% endlist %}.
• Базовые термины вида [текст](*term-id).

Примеры использованияПримеры использованияПримеры использования

Заметка с предупреждением:

{% note warning "Внимание" %}

Текст заметки.

{% endnote %}

Сворачиваемый блок:

{% cut "Заголовок" %}

Скрытое содержимое.

{% endcut %}

Список вкладок:

{% list tabs %}

- Вкладка 1

  Текст вкладки 1.

- Вкладка 2

  Текст вкладки 2.

{% endlist %}

Ссылка на термин:

См. подробнее: [описание термина](*example-term)

Как настроить новую статьюКак настроить новую статьюКак настроить новую статью

1. Создайте файл в формате .md с YFM-разметкой.
2. Заполните frontmatter по article schema: title, description, product, articleType, status, audience, tags.
3. Используйте только поддерживаемые блоки. Для спорных блоков сначала согласуйте их с контент-командой.
4. Проверьте локальный рендер, прежде чем отдавать статью на ревью.
5. Для материалов под редактор и LLM rewrite придерживайтесь YFM-совместимого .md.

Ограничения и нюансыОграничения и нюансыОграничения и нюансы

Следующие сценарии требуют дополнительной проверки или выделенной доработки:

• Локальные изображения из Astro asset pipeline внутри тела YFM.
• MDX-компоненты и Starlight-компоненты внутри .md-страниц.
• Liquid-переменные, include-механики и сложные сценарии переиспользования контента.
• Специализированные блоки file, video, сложные таблицы и кастомные атрибуты без выделенного QA-набора.
• Автоматическое выравнивание старого импортированного контента под новую схему статьи.

Текущая граница v1

Для YFM-совместимого контура безопаснее считать целевым форматом обычные .md-файлы. .mdx остаётся исключением для страниц, которым действительно нужны Astro-компоненты.

Рекомендации по развитию контураРекомендации по развитию контураРекомендации по развитию контура

1. Писать новые материалы для редактора и LLM rewrite в YFM-совместимом .md.
2. Постепенно выводить старые импортированные статьи из legacy-формата в новый шаблон.
3. Для спорных блоков сначала расширять тестовый набор, а затем разрешать их в контент-стандарте.

Связанные статьиСвязанные статьиСвязанные статьи

• Шаблон frontmatter и описание article schema.
• Правила оформления документации в базе знаний.
• Гайд по работе с редактором и LLM rewrite.