Руководство по написанию и форматированию Markdown

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

Добавлять и редактировать документы в EpoCanvas Docs очень просто. Весь основной текст пишется на стандартном синтаксисе Markdown: если вы умеете писать Markdown, вы сразу можете участвовать в создании и сопровождении документации.

Эта страница — полный список поддерживаемых сайтом форматов: раздел 3 по пунктам описывает базовые форматы Markdown, раздел 4 — расширенный синтаксис, поддерживаемый сайтом дополнительно. Для каждого пункта приводится пара «как писать» и «как это выглядит после рендеринга»; то, что вы видите сейчас, — реальный результат рендеринга.

1. Где хранить файлы документации?

Все файлы документации хранятся в каталоге проекта src/content/docs/:

src/content/docs/
├── index.mdx          # Целевая страница (landing page) сайта
├── canvas/            # Ключевые разделы документации (упрощённый китайский, язык по умолчанию)
│   ├── index.md       # Обзор продукта
│   ├── deployment.md  # Быстрый старт
│   ├── layout.md      # Макет страницы
│   ├── ...            # Другие документы
└── en/ ja/ ...        # Переводы на остальные 9 языков; структура каталогов полностью повторяет китайскую

Требования к имени файла: латиница в нижнем регистре и дефисы (например, quickstart-guide.md), без кириллицы и пробелов. Имя файла определяет адрес страницы: canvas/deployment.md соответствует /canvas/deployment/.
Расширение: как правило, достаточно обычного файла .md; если нужно встроить в статью интерактивные компоненты (например, сетку карточек на главной странице), используйте формат .mdx.
Регистрация в боковой панели: после создания файла его нужно внести в массив sidebar в astro.config.mjs, иначе он не появится в оглавлении слева.
Переводы на другие языки: переводы кладутся в каталог src/content/docs/<язык>/, структура подкаталогов повторяет китайскую версию (например, en/canvas/deployment.md соответствует английской странице быстрого старта); если перевод страницы ещё не готов, автоматически показывается китайское содержимое (резервный механизм).

2. Как писать метаданные в шапке (Frontmatter)?

В самом верху каждого Markdown-документа обязательно должен быть блок метаданных YAML, обёрнутый тремя дефисами ---:

---
title: Быстрый старт (запуск за 3 минуты)
description: Руководство по подготовке локального окружения EpoCanvas Docs, установке зависимостей и запуску сервера разработки.
---

Описание полей

Поле	Обязательность	Назначение
`title`	Обязательно	Главный заголовок статьи. Рендерится как крупный заголовок вверху страницы и служит заголовком вкладки браузера.
`description`	Рекомендуется	Краткое резюме статьи. Используется как описание в результатах поиска браузера и в карточках предпросмотра при репосте в соцсети.
`template`	Только для главной страницы	При значении `splash` используется шаблон целевой страницы без боковой панели.

3. Полный обзор базовых форматов Markdown

Сайт рендерит стандартный Markdown с расширениями GFM; все перечисленные ниже форматы поддерживаются. Сначала взгляните на обзор, затем пройдитесь по каждому пункту с парой «как писать — как рендерится»:

Формат	Быстрая запись	Назначение
Заголовки	`## Заголовок раздела`	Структурируют разделы, автоматически попадают в оглавление «На этой странице» справа
Абзацы и переносы	Абзацы разделяются пустой строкой	Базовая единица основного текста
Жирный / курсив / зачёркивание	`жирный` `курсив` `~~зачёркнутый~~`	Выделение важных слов
Строчный код	`команда`	Пометки команд, имён файлов, сочетаний клавиш
Клавиши	`<kbd>Ctrl</kbd>`	Обозначение клавиш в виде клавиш-кнопок
Маркированные / нумерованные списки	`- пункт` / `1. пункт`	Перечисление однопорядковых или пошаговых пунктов
Чек-лист	`- [x] Выполнено`	Контрольный список с чекбоксами
Цитата	`> цитата`	Цитирование первоисточника, примечания на полях
Блок кода	Три обратные кавычки	Многострочный код с подсветкой и кнопкой копирования
Таблицы	Столбцы разделяются вертикальной чертой	Сопоставление параметров, перечисление данных
Ссылки	`[текст](адрес)`	Переход на другую страницу сайта или внешний сайт
Изображения	`![описание](путь)`	Вставка скриншотов и архитектурных схем
Разделительная линия	`---`	Разграничение крупных блоков

3.1 Уровни заголовков

В основном тексте не пишите заголовок первого уровня (#) — title из Frontmatter уже автоматически рендерится как крупный заголовок страницы; ещё один # в тексте приведёт к появлению на странице двух больших заголовков. Разделы начинаются с заголовка второго уровня (##):

## Заголовок второго уровня (раздел)

### Заголовок третьего уровня (подраздел)

Результат рендеринга: страница, которую вы читаете, — готовый пример: «3. Полный обзор базовых форматов Markdown» — заголовок второго уровня, а этот раздел «3.1 Уровни заголовков» — третьего; оба уже попали в оглавление «На этой странице» справа. Заголовки четвёртого уровня (####) оформляются как обычный текст и в оглавление больше не попадают — они подходят для мелких подразделов, которые не нужно показывать в оглавлении.

3.2 Абзацы и переносы строк

В Markdown абзацы разделяются пустой строкой — именно здесь новички чаще всего ошибаются:

Это первый абзац: между двумя предложениями нажата только одна клавиша Enter,
поэтому после рендеринга они остаются в одном абзаце.

Эта строка отделена от предыдущей пустой строкой, и после рендеринга начнётся новый абзац.

В конце этой строки стоит обратный слэш\
поэтому следующая строка действительно начнётся с новой строки.

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

Это первый абзац: между двумя предложениями нажата только одна клавиша Enter, поэтому после рендеринга они остаются в одном абзаце.

Эта строка отделена от предыдущей пустой строкой, и после рендеринга начнётся новый абзац.

В конце этой строки стоит обратный слэш
поэтому следующая строка действительно начнётся с новой строки.

Итог правил: одиночный перевод строки = перенос в исходнике без разрыва абзаца; хотите начать новый абзац — оставьте пустую строку; нужен принудительный перенос внутри абзаца — поставьте обратный слэш в конце строки или два пробела.

3.3 Выделение текста и строчные стили

Это **жирный**, это *курсив*, это ***жирный курсив***, это ~~зачёркнутый~~.

Команды и имена файлов помечаются строчным кодом: выполните `pnpm run dev`, чтобы запустить сервер разработки.

Клавиши оформляются HTML-тегом: <kbd>Ctrl</kbd> + <kbd>K</kbd> открывает поиск по всему сайту.

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

Это жирный, это курсив, это жирный курсив, это ~~зачёркнутый~~.

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

Клавиши оформляются HTML-тегом: Ctrl + K открывает поиск по всему сайту.

3.4 Списки и чек-листы

Неупорядоченный список, вложенные пункты сдвигаются на два пробела:
- Ключевая возможность один
- Ключевая возможность два
  - Подвозможность пункта два
  - Ещё одна подвозможность пункта два

Нумерованный список:
1. Шаг первый: установить Node.js
2. Шаг второй: склонировать репозиторий
3. Шаг третий: запустить сервер разработки

Чек-лист:
- [x] Поддерживается подсветка синтаксиса
- [x] Поддерживается копирование одним кликом
- [ ] Задача в списке ожидания

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

Неупорядоченный список, вложенные пункты сдвигаются на два пробела:

Ключевая возможность один
Ключевая возможность два
- Подвозможность пункта два
- Ещё одна подвозможность пункта два

Нумерованный список:

Шаг первый: установить Node.js
Шаг второй: склонировать репозиторий
Шаг третий: запустить сервер разработки

Чек-лист:

Поддерживается подсветка синтаксиса
Поддерживается копирование одним кликом
Задача в списке ожидания

3.5 Цитаты

> Это цитата. Подходит для выдержек из первоисточника, пояснений контекста или примечаний.
> Несколько строк подряд пишутся внутри одной цитаты.

> > Внутри цитаты можно вложить ещё одну цитату.

> Внутри цитаты тоже можно использовать списки:
>
> - Первый пункт
> - Второй пункт

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

Это цитата. Подходит для выдержек из первоисточника, пояснений контекста или примечаний. Несколько строк подряд пишутся внутри одной цитаты.

Внутри цитаты можно вложить ещё одну цитату.

Внутри цитаты тоже можно использовать списки:

Первый пункт

Второй пункт

3.6 Блоки кода

Оберните код тремя обратными кавычками и укажите язык сразу после первой тройки кавычек — получите подсветку синтаксиса; у каждого блока кода справа есть кнопка копирования одним кликом:

```js
export function formatBytes(bytes) {
  return `${(bytes / 1024).toFixed(1)} KB`;
}
```

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

export function formatBytes(bytes) {
  return `${(bytes / 1024).toFixed(1)} KB`;
}

Язык определяет схему подсветки; поддерживаются распространённые js, ts, bash, json, yaml, html, css, python и другие. Терминальные языки вроде bash рендерятся с тёмной рамкой в стиле терминала:

pnpm run build

Продвинутые приёмы — заголовок с именем файла, подсветка конкретных строк и другие — описаны в разделе 4.2.

3.7 Таблицы

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

| Команда | Параметр | Описание |
| :--- | :---: | ---: |
| `astro dev` | `--host` | Пример выравнивания по левому краю |
| `astro build` | нет | Пример выравнивания по центру |
| `astro preview` | `--port` | Пример выравнивания по правому краю |

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

Команда	Параметр	Описание
`astro dev`	`--host`	Пример выравнивания по левому краю
`astro build`	нет	Пример выравнивания по центру
`astro preview`	`--port`	Пример выравнивания по правому краю

3.8 Ссылки

Внутренняя ссылка: [Быстрый старт](/canvas/deployment/)

Внешняя ссылка: [Официальный сайт Astro](https://astro.build)

Якорь на этой странице: [перейти к разделу «Таблицы»](#37-таблицы)

Автоссылка: <https://github.com/shijianus/epocanvas-docs>

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

Внутренняя ссылка: Быстрый старт

Внешняя ссылка: Официальный сайт Astro

Якорь на этой странице: перейти к разделу «Таблицы»

Автоссылка: https://github.com/shijianus/epocanvas-docs

Правила записи:

Внутренние ссылки задаются полным путём, начинающимся и заканчивающимся на / (например, /canvas/deployment/), относительные пути использовать не нужно;
Якорь — это ID, полученный из текста заголовка; якорь кириллического заголовка — сам текст заголовка (пунктуация убирается, пробелы заменяются дефисами); чтобы скопировать ссылку с якорем, достаточно скопировать адрес из адресной строки браузера;
Текст ссылки должен ясно указывать, куда она ведёт, — не пишите «нажмите здесь».

3.9 Изображения и подписи

Все изображения для документации складывайте в каталог public/images/canvas/, а в ссылках используйте абсолютный путь, начинающийся с /:

![Реальный вид страницы быстрого старта на локальном сервере разработки](/images/canvas/ui-quickstart.png)

*Рисунок: курсивная строка сразу под изображением отображается как подпись к нему.*

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

Реальный вид страницы быстрого старта на локальном сервере разработки

Рисунок: реальный вид страницы быстрого старта, здесь — только демонстрация.

Требования к изображениям:

Архитектурные схемы и блок-схемы: сохраняйте в векторном формате .svg — при увеличении на телефоне и экранах с высокой плотностью картинка не размывается. Все схемы этого сайта лежат в public/images/canvas/docs-*.svg.
Скриншоты интерфейса: сохраняйте в сжатом .png, ширины около 1440 пикселей достаточно; не загружайте напрямую исходники размером в десятки мегабайт.
Описание обязательно: текст внутри ![ ] рендерится как альтернативный текст изображения — добросовестно опишите, что на картинке, не оставляйте поле пустым.

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

3.10 Разделительные линии

Три дефиса и больше на отдельной строке рендерятся как разделительная линия для разграничения крупных блоков:

Предыдущая тема закончена.

---

Начинается новая тема.

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

Предыдущая тема закончена.

Начинается новая тема.

4. Расширенные форматы: синтаксис, добавленный на этом сайте

Эти форматы — расширенный синтаксис, который сайт поддерживает поверх стандартного Markdown; его обеспечивают движки рендеринга (выноски Starlight и Expressive Code).

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

Выноски используют синтаксис с тремя двоеточиями: начало — :::тип, конец — ::: на отдельной строке; всего четыре типа, у каждого свои цвет и значок:

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

:::tip[Ускорение установки]
Установка зависимостей через pnpm заметно быстрее, чем через npm:

```bash
npm install -g pnpm
```
:::

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

Внутри выноски можно использовать любые элементы оформления — списки, блоки кода, таблицы и т. д.; больше примеров в разделе Примеры выносок, блоков кода и диаграмм.

4.2 Заголовок с именем файла и подсветка строк в блоках кода

Укажите в первой строке код-фенса title="путь к файлу", чтобы показать строку заголовка, и {номера строк} для подсветки важных строк; несколько номеров перечисляются через запятую:

```typescript title="src/config/site.ts" {2,4}
export const siteConfig = {
  name: 'EpoCanvas Docs', // ← подсвеченная строка
  version: '1.0.0',
  locale: 'zh-CN',        // ← подсвеченная строка
};
```

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

export const siteConfig = {
  name: 'EpoCanvas Docs',
  version: '1.0.0',
  locale: 'zh-CN',
};

4.3 Сравнение изменений (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',
});

4.4 Сноски

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

Полнотекстовый поисковый индекс всего сайта генерируется Pagefind на этапе сборки[^pf].

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

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

4.5 Шпаргалка: что не поддерживается и где легко ошибиться

Эти приёмы распространены на других платформах, но на этом сайте не работают или ведут себя не так, как ожидается; при написании документации сразу обходите их стороной:

Частая ошибка	Что происходит на самом деле	Правильная замена
Код-фенс ```mermaid	Показывает исходник как обычный блок кода, диаграмма не строится	Экспортируйте SVG на mermaid.live и вставьте как изображение
`> [!NOTE]` — синтаксис уведомлений GitHub	Рендерится как обычная цитата	Перепишите на `:::note`
`:::warning` / `:::important`	Молча рендерится как обычный абзац, без стиля выноски	Перепишите на `:::caution`
Заголовок первого уровня `#` в основном тексте	На странице появляются два больших заголовка	Уберите `#`, основной текст начинается с `##`
Одиночный перенос строки в надежде на разрыв	Две строки сливаются в одну	Разделяйте абзацы пустой строкой или ставьте обратный слэш в конце строки

5. Что дальше

Хотите узнать полный конвейер рендеринга Markdown от файла до страницы и все соглашения по синтаксису? Читайте Правила рендеринга.
Хотите увидеть выноски, блоки кода, сноски и другой синтаксис в одном «живом примере»? Читайте Примеры выносок, блоков кода и диаграмм.

Это и есть настоящая сноска, отрендеренная внизу этой страницы — где бы в тексте ни была написана сноска, все они собираются в самом низу страницы. ↩