Примеры выносок, блоков кода и диаграмм

Последнее обновление: 13 сент. 2026 г. / Официальная архитектурная спецификация EpoCanvas

Для качественной технической документации нужны не только ясный текст, но и заметные выделения главного, аккуратно оформленные примеры кода и наглядные схемы. Все примеры на этой странице — реально работающий синтаксис: то, что вы видите, и есть результат рендеринга, — сама статья является живой страницей-примером.

1. Четыре цветные выноски

Выноски используют синтаксис тройного двоеточия: открываются :::type, закрываются :::, между ними пишется содержимое. Сайт основан на Starlight и поддерживает четыре типа: note, tip, caution, danger.

Синтаксис и реальный эффект: сравнение

Внутри выноски может быть любое содержимое

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

2. Расширенное оформление блоков кода

2.1 Заголовок с именем файла и подсветка заданных строк

В первой строке кодового ограждения укажите title="путь к файлу" и подсветите важные строки через {номера строк}:

```typescript title="src/config/site.ts" {2}
export const siteConfig = {
  name: 'EpoCanvas Docs', // эта строка будет выделена подсветкой фона
  version: '1.2.0',
};
```

Результат рендеринга:

export const siteConfig = {
  name: 'EpoCanvas Docs',
  version: '1.2.0',
};

2.2 Сравнение изменений кода (diff)

Показывая обновление конфигурации или рефакторинг кода, используйте язык diff, чтобы изменения были видны с первого взгляда: строки, начинающиеся с -, отображаются как удалённые, начинающиеся с + — как добавленные:

```diff
  export default defineConfig({
-   site: 'http://localhost:3000',
+   site: 'https://docs.epocanvas.com',
  });
```

Результат рендеринга:

export default defineConfig({
  site: 'http://localhost:3000',
  site: 'https://docs.epocanvas.com',
});

2.3 Терминальные команды

Терминальные языки bash, sh, powershell и другие рендерятся с тёмной рамкой в стиле терминала:

pnpm run build

3. Как вставить диаграмму

В текущей версии рендеринг текстовых диаграмм вроде Mermaid не встроен. Написанное напрямую ограждение ```mermaid отобразится как обычный блок кода с исходным кодом, без построения графики.

Рекомендуемый подход: написать диаграмму и экспортировать векторный SVG в инструменте вроде mermaid.live, сохранить его в public/images/canvas/ и вставить синтаксисом изображений. Именно так сделаны архитектурная схема и схема процесса переключения языка на этом сайте:

Схема архитектуры системы

Рисунок: архитектурная схема, вставленная как SVG-изображение, — масштабируется без потери чёткости.

Если всё же нужно, чтобы исходник Mermaid рендерился в график напрямую, в проект придётся добавить дополнительный плагин рендеринга (например, rehype-mermaid); это уже доработка проекта — вводите её после оценки затрат на сопровождение.

4. Другая полезная вёрстка

встроенный код: pnpm run dev — рендерится моноширинным шрифтом цвета темы;
клавиши: Ctrl + K — рендерятся в стиле клавиатурных клавиш;
список задач:

- [x] Поддержка подсветки синтаксиса
- [x] Поддержка копирования одним нажатием
- [ ] Встроенный рендеринг Mermaid (в планах)

Рендерится в виде пунктов списка с состоянием отметки.

4.1 Сноски

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

Статический индекс генерируется Pagefind при сборке[^pagefind].

[^pagefind]: [Официальная документация Pagefind](https://pagefind.app/) — библиотека локального поиска для статических сайтов.

Результат рендеринга: в конце фразы в основном тексте появится надстрочный маркер перехода с номером¹, по клику происходит плавный переход к списку сносок внизу страницы.

Умелое использование выносок, аннотаций кода и схем заметно повышает комфорт чтения технической документации и ощущение профессионализма. Полные соглашения по синтаксису описаны в статье Подробно о правилах рендеринга.

Это и есть сноска, отрендеренная внизу этой страницы. ↩