Привет! Как вы, возможно, заметили, этот сайт документации полностью открыт и доступен для редактирования на GitHub. Вы можете найти страницу этого сайта на GitHub по адресу https://github.com/space-sorcerers/docs.
Есть несколько моментов, которые стоит учитывать при участии. Хотя мы запрещаем web-edit PR (сделанные исключительно на GitHub) в основные репозитории Space Station 14 и Robust Toolbox, здесь это не так. Web-редактирование приветствуется, чтобы сделать редактирование документации максимально безболезненным.
Если вы хотите узнать, какие возможности доступны при написании документации, перейдите на Пример страницы документации.
Стиль
Документация должна быть написана в стиле технической коммуникации. Эффективная техническая коммуникация должна быть краткой, точной, прямой и хорошо организованной, написана соответствующим голосом и тоном с использованием правильной грамматики и пунктуации, со ссылками на соответствующие источники при необходимости.
Быстрые правки через GitHub
Если вы хотите просто внести небольшую правку в страницу, выполните следующие шаги — вам не понадобится ничего из описанного далее:
- Создайте аккаунт на GitHub или войдите, если он уже есть.
- Сделайте fork репозитория space-sorcerers/docs на GitHub.
- Нажмите на иконку «View & Edit Page on GitHub» в правом верхнем углу любой страницы этого сайта.
- Нажмите кнопку «Edit this file» в правом верхнем углу просмотра файла.
- Внесите изменения, затем сделайте commit и создайте pull request! Мы сделаем всё остальное.
Локальная сборка
Установка
Требуется Node.js v20.17.0 или новее.
Установите CLI Mintlify глобально:
Запуск dev-сервера
Из корня проекта:
Откроется локальный предпросмотр по адресу http://localhost:3000 с горячей перезагрузкой при изменении файлов.
Проверка на ошибки
Проверяет синтаксис всех .mdx файлов и навигацию. Запускается в CI при каждом PR.
Обновление CLI
Форматирование
Для подсветки синтаксиса и форматирования MDX-файлов используйте расширения:
Проверка изменений
Если вы создали PR, проще всего проверить изменения во вкладке «Files changed» в GitHub. Также можно использовать локальное расширение для предпросмотра markdown, например, для VSCode.
Для аутентичного предпросмотра каждый PR будет автоматически развёрнут через Mintlify preview. Ссылку можно найти в разделе проверок PR.
Ревью
Мейнтейнеры будут проверять pull request для документации на содержание и стиль. Мейнтейнеры понимают, что многие участники не являются носителями языка, и будут полезны в своих комментариях к ревью.
Чтобы максимально эффективно использовать время мейнтейнеров, перед отправкой, пожалуйста:
- Вычитайте свои изменения
- Используйте проверку орфографии
- Рассмотрите использование инструментов проверки грамматики, таких как Grammarly
Синтаксис MDX
Мы используем MDX — Markdown с возможностью встраивать JSX-компоненты. Ниже — основные конструкции.
Заголовки
Пользовательские ID
Ссылка: #custom-anchor.
Отключение привязки
Форматирование текста
Ссылки
Блочные цитаты
Разделители
Переносы строк
Комментарии MDX
HTML-комментарии <!-- --> в MDX не работают. Используйте {/* */}.
Экранирование специальных символов
В MDX фигурные скобки ({}) и угловые скобки (<>) имеют специальное значение. Чтобы вывести их как обычный текст, оберните в обратные кавычки или используйте HTML-сущности:
Математические выражения
Строчные: $E = mc^2$
Блочные:
Таблицы
Выравнивание столбцов:
Списки
Изображения
С тёмной/светлой темой:
Блоки кода
Обычный блок
С заголовком
С иконкой
Подсветка строк
Фокус на строках
Номера строк
Сворачиваемый блок
Перенос строк
Дифф (различия)
Группы кода (CodeGroup)
Синхронизируются по заголовкам с другими CodeGroup и Tabs на странице:
Для выпадающего списка вместо вкладок:
Компоненты Mintlify
Callouts
Кастомный:
Accordion
Группа:
Badge
Cards
Columns
Frame (для изображений)
Icons
Steps
Tabs
Вкладки с одинаковыми названиями синхронизируются по всей странице.
Tiles
Tree (файловая структура)
Mermaid (диаграммы)
С ELK-рендерингом:
Visibility (показывать разный контент людям и AI)
Переиспользуемые сниппеты
Создайте файл в /snippets/ и импортируйте его на любую страницу:
С переменными:
Frontmatter (YAML-шапка)
Каждый .mdx файл начинается с ---:
Полезные поля:
SEO и мета-теги
Глобальные мета-теги задаются в docs.json:
Канонические URL
OG-изображения
По умолчанию Mintlify генерирует OG-картинку автоматически. Можно задать фоновое изображение:
Карта сайта и robots.txt
Mintlify генерирует sitemap.xml и robots.txt автоматически. Чтобы добавить свой robots.txt, создайте файл robots.txt в корне проекта.
Content-Signal (AI-индексация)
Mintlify добавляет в robots.txt директивы Content-Signal:
Редиректы
При перемещении страниц настройте редиректы в docs.json:
С wildcard:
Поиск
Boost (приоритет страницы)
В frontmatter страницы:
Или для целой группы в docs.json:
Максимум результатов
Настраивается в дашборде Mintlify: Settings → Deployment → Search → Maximum search results.
Изменение docs.json
Не меняйте docs.json без явной необходимости. Это конфигурация всего сайта: навигация, редиректы, темы, SEO.
Основные секции docs.json:
navigation — структура боковой панели и локализация
redirects — редиректы
seo — мета-теги и поисковая оптимизация
colors — цвета темы
styling.codeblocks — темы подсветки кода
banner — баннер в верхней части сайта
Последнее изменение 21 июня 2026 г.