Подробно о правилах рендеринга

На этой странице подробно описаны правила рендеринга EpoCanvas Docs: через какие этапы обработки проходит Markdown-файл, во что превращается каждый синтаксис и какой синтаксис не поддерживается. Прочтите её один раз перед написанием документации — это позволит избежать большинства проблем с вёрсткой.

---

Конвейер рендеринга: от .md-файла до страницы на сайте

Рисунок: 5 шагов конвейера рендеринга Markdown. Шаги выполняются по порядку на этапе сборки; результат сборки — чисто статические файлы, без накладных расходов клиентского фреймворка во время выполнения.

От сохранения до появления перед читателем Markdown-файл проходит следующие пять этапов:

1. Сбор контента: при запуске или сборке Astro сканирует каталог src/content/docs/, регистрирует каждый файл .md / .mdx как запись контента и проверяет Frontmatter (отсутствие title сразу вызывает ошибку).
2. Компиляция Markdown: основной текст компилятором Markdown (с расширениями GFM) преобразуется в HTML. Расширенный синтаксис — таблицы, списки задач, зачёркивание и т.д. — срабатывает на этом шаге.
3. Подсветка блоков кода: все кодовые ограждения обрабатывает Expressive Code, создавая блоки кода с подсветкой синтаксиса, панелью заголовка, номерами строк и кнопкой копирования.
4. Применение макета сайта: скомпилированный HTML вставляется в каркас страницы Starlight — верхняя панель, левое оглавление и правое оглавление страницы рендерятся кастомными компонентами из src/components/starlight/.
5. Генерация индекса и статических файлов: при pnpm run build Pagefind обходит все итоговые страницы и извлекает полнотекстовый индекс; чистый HTML в каталоге dist/ можно размещать на любом статическом сервере.

Заметка

Весь описанный процесс выполняется один раз на этапе сборки. После публикации сайта сервер не участвует: все взаимодействия (поиск, переключение темы, переключение языка) происходят в браузере.

---

Правила Frontmatter

• title обязателен; при его отсутствии сборка завершается ошибкой InvalidInputError;
• description рекомендуется заполнять: он показывается в результатах поисковых систем и в карточках при обмене ссылками;
• Frontmatter должен быть корректным YAML-блоком в самом начале файла; все три дефиса в разделителях обязательны.

---

Правила заголовков

Правило	Пояснение
Не пишите заголовок первого уровня # в основном тексте	title из Frontmatter уже отрендерен как крупный заголовок страницы; ещё один # в тексте даст два крупных заголовка
Основной текст начинается с заголовка второго уровня ##	## и ### автоматически попадают в правое «оглавление страницы»
#### и глубже не попадают в оглавление	Более глубокие уровни рендерятся только как стили основного текста
Текст заголовка превращается в якорь	Якорь китайского заголовка — сами китайские символы, например #标题规则

---

Правила выносок (Asides)

Выноски используют синтаксис тройного двоеточия Starlight и поддерживают 4 типа:

:::note
Дополнительное пояснение.
:::

:::tip
Небольшой приём для повышения эффективности.
:::

:::caution
Риск, на который стоит обратить внимание, или операция, в которой легко ошибиться.
:::

:::danger
Предупреждение о высокой опасности: потеря данных или необратимые операции.
:::

После типа можно добавить собственный заголовок: :::tip[Быстрая установка].

Осторожно

Обратите внимание на две частые ошибки:

• синтаксис цитаты в стиле GitHub > [!TIP] не поддерживается: написанный [!TIP] отобразится обычным текстом внутри цитаты;
• :::important и :::warning не являются допустимыми типами: ошибки не будет, но они молча отрендерятся как обычные абзацы.

При переносе старых документов: > [!NOTE] → :::note, > [!WARNING] → :::caution, > [!CAUTION] → :::danger.

Рисунок: реальное отображение четырёх выносок, записанных по приведённому выше синтаксису; скриншот со страницы Примеры выносок, блоков кода и диаграмм.

---

Правила блоков кода

Кодовые ограждения (три обратных апострофа) рендерит Expressive Code; поддерживаются следующие аннотации (пишутся после обратных апострофов первой строки):

Аннотация	Назначение	Пример
Идентификатор языка	Определяет схему подсветки синтаксиса	```ts
title="..."	Показывает панель заголовка с именем файла	```ts title=“src/config/site.ts”
{2} / {2-4}	Подсвечивает указанные строки	```ts {2}
lang="diff" или diff	Показывает добавленные и удалённые строки в красно-зелёном сравнении	```diff
bash / sh и другие терминальные языки	Рендерится с рамкой в стиле терминала	```bash

К каждому блоку кода автоматически добавляется кнопка копирования одним нажатием; текст кода попадает в поисковый индекс Pagefind, поэтому ключевые слова из кода можно находить поиском напрямую.

---

Правила изображений

• Изображения хранятся в едином каталоге public/images/canvas/ и подключаются абсолютным путём: ![описание](/images/canvas/ui-docs-reading.png);
• архитектурные и процессные схемы — в векторном формате .svg, скриншоты интерфейса — в сжатом .png;
• описание обязательно к заполнению: это альтернативный текст на случай неудачной загрузки изображения и основа для доступности;
• в текущей версии рендеринг диаграмм Mermaid не встроен: ограждение ```mermaid отобразится как обычный блок кода с исходным кодом. Если нужна блок-схема, сначала экспортируйте SVG в mermaid.live или подобном инструменте, а затем вставьте её как изображение.

---

Правила ссылок

• Внутренние ссылки: указывайте полный путь, начинающийся и заканчивающийся на /, например /canvas/deployment/. После изменения пути документа старый путь нужно зарегистрировать в таблице redirects в astro.config.mjs;
• Якорные ссылки: /canvas/rendering/#правила-блоков-кода ведёт сразу к нужному разделу этой страницы;
• Внешние ссылки: достаточно указать полный URL; в основном тексте они отображаются цветом темы.

---

Прочее поведение рендеринга

Синтаксис	Результат рендеринга
**жирный**, *курсив*, ~~зачёркнутый~~	Соответствующее начертание текста
встроенный код	Капсула моноширинным шрифтом цвета темы
Запись Ctrl+K	Обозначение клавиш в стиле клавиатурных клавиш
Таблицы GFM	Таблицы данных с рамкой и подсветкой при наведении
Список задач - [x]	Визуальные чекбоксы (в отключённом состоянии)
Сноски [^сноска]	Верхний индекс в основном тексте + список сносок внизу страницы, с переходами по клику в обе стороны
Цитата Markdown >	Вертикальная линия цвета темы слева + светлый фон
Разделитель ---	Тонкая линия через всю область основного текста

Совет

Если не уверены, как отрендерится тот или иной синтаксис, самый надёжный способ: запустите pnpm run dev, вставьте небольшой фрагмент в тестовый документ и убедитесь в браузере своими глазами, прежде чем использовать его в основном документе.