Перейти к основному содержимому

Гайд по оформлению документации

Цель​

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

Структура страницы​

  • Заголовок H1: кратко и по делу.
  • Краткое описание (1–3 предложения) сразу после H1.
  • Содержание: логические секции H2 → подпункты H3.
  • Конец страницы: ссылки «Далее/Назад» формируются автоматически.

Frontmatter (верх страницы)​

Используйте в .md/.mdx:

---
sidebar_position: <число>
title: <Заголовок на странице>
description: <1–2 предложения, отображается в SEO/превью>
---

Рекомендации:

  • sidebar_position: шаги в Quickstart — 1, 2, 3…; в остальных разделах — кратная десяткам нумерация (10, 20, 30) с запасом.
  • id указывать только при необходимости уникального слага.

Именование файлов и слагов​

  • Файлы: латиница, строчные, дефисы: booking-create.mdx.
  • Папки отражают разделы: features/booking/booking-create.mdx.
  • Внутренние якоря: ### Настройки {#settings} — только если есть внешние ссылки на якорь.

Базовые элементы​

  • Заголовки: H2 для основных разделов, H3 для подпунктов. Не пропускайте уровни.
  • Списки: используйте маркированные для перечней, нумерованные — для последовательностей.
  • Таблицы: только для строгих матриц значений, не для верстки.
  • Подчёркивания/курсив: умеренно; акценты — через короткие заметки.

Разделители и блоки​

  • Визуальный разделитель:
<div style="border-top: 1px solid var(--ifm-toc-border-color); margin: 1rem 0;"></div>
  • Заметки (admonitions):
:::tip
Короткий совет.
:::

:::info
Полезная информация.
:::

:::warning
Осторожно: потенциальные риски.
:::

:::danger
Не делайте так в продакшене.
:::

Компоненты и вставки​

  • Код:
```bash
npm run start
- Инлайн-код: `
`optionName`
`.
- Ссылки — читаемые названия, не голые URL.

## Изображения
- Расположение: `static/img/<подраздел>/<файл>`.
- Форматы: предпочтительно `.png` для интерфейсов, `.jpg` для фото, `.svg` для иконок. По возможности используйте сжатие без потери читаемости.
- Размеры: до 1600 px по большей стороне; целевые веса — до 300 КБ (для гайдовых скриншотов до 500 КБ). Сохраняйте читабельность текста.
- Имена: латиница, дефисы: `booking-table-edit.jpg`.
- Вставка:
```mdx
import img from '@site/static/img/features/booking-create-button.png';

<img src={img} alt="Кнопка создания бронирования" width="800" />
  • Подпись к картинке — обычным абзацем сразу после изображения (курсив):
_Подпись к изображению._

Навигация и сайдбар​

  • Подключение страницы — через sidebars.ts соответствующего раздела.
  • Не перегружайте корневой уровень, группируйте в категории.

Быстрый чек-лист перед коммитом​

  • Заголовки и фронтматтер заполнены.
  • Секции логично структурированы (H2/H3), есть краткое вступление.
  • Изображения оптимизированы, имеют осмысленные alt-тексты.
  • Нет «висячих» ссылок; локальные пути проверены.
  • Страница добавлена в sidebars.ts (если это часть портала).

Примеры хороших страниц​

  • Quickstart: короткие шаги, иллюстрации, ссылки на детали.
  • Features: сценарии использования, скриншоты, указание пути в интерфейсе.

Частые ошибки​

  • Слишком длинные заголовки H1.
  • Смешение русского и транслита в именах файлов.
  • Картинки «в полотно» без ограничения ширины.
  • Необоснованные таблицы.

Если чего-то не хватает в гайде — дополните разделом или предложите правку.