Перейти к основному содержанию
Привет! Как вы, возможно, заметили, этот сайт документации полностью открыт и доступен для редактирования на GitHub. Вы можете найти страницу этого сайта на GitHub по адресу https://github.com/space-sorcerers/docs. Есть несколько моментов, которые стоит учитывать при участии. Хотя мы запрещаем web-edit PR (сделанные исключительно на GitHub) в основные репозитории Space Station 14 и Robust Toolbox, здесь это не так. Web-редактирование приветствуется, чтобы сделать редактирование документации максимально безболезненным. Если вы хотите узнать, какие возможности доступны при написании документации, перейдите на Пример страницы документации.

Стиль

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

Быстрые правки через GitHub

Если вы хотите просто внести небольшую правку в страницу, выполните следующие шаги — вам не понадобится ничего из описанного далее:
  1. Создайте аккаунт на GitHub или войдите, если он уже есть.
  2. Сделайте fork репозитория space-sorcerers/docs на GitHub.
  1. Нажмите на иконку «View & Edit Page on GitHub» в правом верхнем углу любой страницы этого сайта.
  1. Нажмите кнопку «Edit this file» в правом верхнем углу просмотра файла.
  1. Внесите изменения, затем сделайте commit и создайте pull request! Мы сделаем всё остальное.

Локальная сборка

Установка

Требуется Node.js v20.17.0 или новее. Установите CLI Mintlify глобально:
npm i -g mint

Запуск dev-сервера

Из корня проекта:
mint dev
Откроется локальный предпросмотр по адресу http://localhost:3000 с горячей перезагрузкой при изменении файлов.

Проверка на ошибки

npx mintlify validate
Проверяет синтаксис всех .mdx файлов и навигацию. Запускается в CI при каждом PR.

Обновление CLI

mint update

Форматирование

Для подсветки синтаксиса и форматирования MDX-файлов используйте расширения:

Проверка изменений

Если вы создали PR, проще всего проверить изменения во вкладке «Files changed» в GitHub. Также можно использовать локальное расширение для предпросмотра markdown, например, для VSCode. Для аутентичного предпросмотра каждый PR будет автоматически развёрнут через Mintlify preview. Ссылку можно найти в разделе проверок PR.

Ревью

Мейнтейнеры будут проверять pull request для документации на содержание и стиль. Мейнтейнеры понимают, что многие участники не являются носителями языка, и будут полезны в своих комментариях к ревью. Чтобы максимально эффективно использовать время мейнтейнеров, перед отправкой, пожалуйста:
  • Вычитайте свои изменения
  • Используйте проверку орфографии
  • Рассмотрите использование инструментов проверки грамматики, таких как Grammarly

Синтаксис MDX

Мы используем MDX — Markdown с возможностью встраивать JSX-компоненты. Ниже — основные конструкции.

Заголовки

## Заголовок секции
### Подзаголовок
#### Подподзаголовок

Пользовательские ID

## Моя секция {#custom-anchor}
Ссылка: #custom-anchor.

Отключение привязки

<h2 noAnchor>
Заголовок без якоря
</h2>

Форматирование текста

СтильСинтаксисРезультат
Жирный**текст**жирный текст
Курсив_текст_курсив
Зачёркнутый~текст~зачёркнутый
Верхний индекс<sup>текст</sup>обычныйверхний
Нижний индекс<sub>текст</sub>обычныйнижний

Ссылки

[Внутренняя страница](/ru/meta/guide-to-editing-docs)
[Внешний ресурс](https://example.com)

Блочные цитаты

> Это цитата.
>
> Второй абзац цитаты.

Разделители

---

Переносы строк

Строка до.<br />
Строка после.

Комментарии MDX

{/* Это комментарий — он не попадёт в собранную страницу */}
HTML-комментарии <!-- --> в MDX не работают. Используйте {/* */}.

Экранирование специальных символов

В MDX фигурные скобки ({}) и угловые скобки (<>) имеют специальное значение. Чтобы вывести их как обычный текст, оберните в обратные кавычки или используйте HTML-сущности:
Синтаксис `{variable}` для подстановки значений.
Стрелочка `->` — это не JSX.

Математические выражения

Строчные: $E = mc^2$ Блочные:
$$
E = mc^2
$$

Таблицы

| Свойство | Тип     | Описание          |
| -------- | ------- | ----------------- |
| Name     | `string`| Имя пользователя  |
| Age      | `int`   | Возраст           |
Выравнивание столбцов:
| По левую | По центру | По правую |
| :------- | :-------: | --------: |
| left     |  center   |     right |

Списки

1. Первый пункт
2. Второй пункт
   - Вложенный пункт
   - Ещё вложенный
3. Третий пункт

Изображения

![Описание изображения](/images/example.png)
С тёмной/светлой темой:
<img className="block dark:hidden" src="/images/light.png" alt="Светлая тема" />
<img className="hidden dark:block" src="/images/dark.png" alt="Тёмная тема" />

Блоки кода

Обычный блок

```csharp
public sealed class GreeterSystem : EntitySystem
{
    public void GreetEveryone(string message)
    {
        Logger.Info(message);
    }
}
```

С заголовком

```csharp GreeterSystem.cs
public void GreetEveryone(string message)
```

С иконкой

```yaml icon=file-yaml
- type: Greeter
  message: "Hello!"
```

Подсветка строк

```csharp highlight={1,3-5}
public sealed class GreeterSystem : EntitySystem
{
    public void GreetEveryone(string message)
    {
        Logger.Info(message);
    }
}
```

Фокус на строках

```csharp focus={2,4}
public sealed class GreeterSystem : EntitySystem
{
    public void GreetEveryone(string message)
    {
        Logger.Info(message);
    }
}
```

Номера строк

```csharp lines
public void GreetEveryone(string message)
{
    Logger.Info(message);
}
```

Сворачиваемый блок

```csharp expandable
// Длинный код, который можно свернуть
Console.WriteLine("Hello!");
```

Перенос строк

```csharp wrap
var message = "This is a very long line of code that will wrap to the next line instead of scrolling horizontally.";
```

Дифф (различия)

```csharp lines
public void OldMethod() 
public void NewMethod() 
```

Группы кода (CodeGroup)

Синхронизируются по заголовкам с другими CodeGroup и Tabs на странице:
<CodeGroup>
```csharp Greeter.cs
Console.WriteLine("Hello!");
```
```python greeter.py
print("Hello!")
```
```bash greeter.sh
echo "Hello!"
```
</CodeGroup>
Для выпадающего списка вместо вкладок:
<CodeGroup dropdown>
  ...
</CodeGroup>

Компоненты Mintlify

Callouts

<Note>   Примечание   </Note>
<Info>   Информация   </Info>
<Tip>    Совет        </Tip>
<Warning>Предупреждение</Warning>
<Danger> Опасность     </Danger>
<Check>  Готово        </Check>
Кастомный:
<Callout icon="key" color="#FFC107">Произвольный callout</Callout>

Accordion

<Accordion title="Заголовок">
  Скрытое содержимое.
</Accordion>
Группа:
<AccordionGroup>
  <Accordion title="Раздел 1">...</Accordion>
  <Accordion title="Раздел 2" icon="bot">...</Accordion>
</AccordionGroup>

Badge

<Badge>Обычный</Badge>
<Badge color="green" size="sm">Готово</Badge>
<Badge color="orange" size="lg" shape="pill">Beta</Badge>
<Badge icon="star" color="blue">Избранное</Badge>

Cards

<Card title="Заголовок" icon="book" href="/ru/page">
  Описание карточки.
</Card>

<Card title="Горизонтальная" icon="rocket" horizontal>
  Компактный вариант.
</Card>

Columns

<Columns cols={2}>
  <Card title="Колонка 1">...</Card>
  <Card title="Колонка 2">...</Card>
</Columns>

Frame (для изображений)

<Frame caption="Подпись под изображением">
  <img src="/images/example.png" alt="Описание" />
</Frame>

Icons

<Icon icon="flag" size={32} />
<Icon icon="star" color="#FFD700" />

Steps

<Steps>
  <Step title="Шаг 1">
    Инструкция для первого шага.
  </Step>
  <Step title="Шаг 2">
    Инструкция для второго шага.
  </Step>
</Steps>

Tabs

<Tabs>
  <Tab title="Windows">
    Инструкция для Windows.
  </Tab>
  <Tab title="Linux" icon="linux">
    Инструкция для Linux.
  </Tab>
</Tabs>
Вкладки с одинаковыми названиями синхронизируются по всей странице.

Tiles

<Tile href="/page" title="Заголовок" description="Описание">
  <img src="/images/tile.png" alt="Tile preview" />
</Tile>

Tooltip

<Tooltip tip="Определение термина" headline="Термин" cta="Читать далее" href="/page">
  термин
</Tooltip>

Tree (файловая структура)

<Tree>
  <Tree.Folder name="content" defaultOpen>
    <Tree.File name="index.yml" />
    <Tree.Folder name="maps">
      <Tree.File name="station.yml" />
    </Tree.Folder>
  </Tree.Folder>
  <Tree.File name="meta.json" />
</Tree>

Mermaid (диаграммы)

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```
С ELK-рендерингом:
```mermaid
%%{init: {'flowchart': {'defaultRenderer': 'elk'}}}%%
flowchart LR
    A[Start] --> B[Process]
    B --> C[End]
```

Visibility (показывать разный контент людям и AI)

<Visibility for="humans">
  Видно только в браузере.
</Visibility>

<Visibility for="agents">
  Видно только AI-агентам в Markdown-экспорте.
</Visibility>

Переиспользуемые сниппеты

Создайте файл в /snippets/ и импортируйте его на любую страницу:
import SetupGuide from "/snippets/setup-guide.mdx";

<SetupGuide />
С переменными:
import InstallSnippet from "/snippets/install.mdx";

<InstallSnippet packageName="MyMod" />

Frontmatter (YAML-шапка)

Каждый .mdx файл начинается с ---:
---
title: "Название страницы"
description: "Описание для поисковиков и превью"
sidebar_position: 5
---

Полезные поля:
ПолеОписание
titleЗаголовок страницы
descriptionОписание (SEO, превью)
sidebar_positionПорядок в боковой панели
noindextrue — скрыть от поисковиков
canonicalКанонический URL
og:titleСвой заголовок для соцсетей
og:imageСвоя картинка для превью
boostПриоритет в поиске (1.0 = обычный)
groupsДоступно только указанным группам
drafttrue — черновик, не публикуется

SEO и мета-теги

Глобальные мета-теги задаются в docs.json:
"seo": {
  "metatags": {
    "og:image": "https://docs.ss14.art/images/og.png",
    "google-site-verification": "..."
  }
}

Канонические URL

"seo": {
  "metatags": {
    "canonical": "https://docs.ss14.art"
  }
}

OG-изображения

По умолчанию Mintlify генерирует OG-картинку автоматически. Можно задать фоновое изображение:
"thumbnails": {
  "background": "/images/og-background.png"
}

Карта сайта и robots.txt

Mintlify генерирует sitemap.xml и robots.txt автоматически. Чтобы добавить свой robots.txt, создайте файл robots.txt в корне проекта.

Content-Signal (AI-индексация)

Mintlify добавляет в robots.txt директивы Content-Signal:
Content-Signal: ai-train=yes, search=yes, ai-input=yes

Редиректы

При перемещении страниц настройте редиректы в docs.json:
"redirects": [
  {
    "source": "/old/path",
    "destination": "/new/path"
  }
]
С wildcard:
"redirects": [
  {
    "source": "/ru/:slug*",
    "destination": "/en/:slug*"
  }
]

Поиск

Boost (приоритет страницы)

В frontmatter страницы:
---
boost: 3
---
Или для целой группы в docs.json:
{
  "group": "Getting started",
  "boost": 5,
  "pages": ["quickstart", "concepts"]
}

Максимум результатов

Настраивается в дашборде Mintlify: Settings → Deployment → Search → Maximum search results.

Изменение docs.json

Не меняйте docs.json без явной необходимости. Это конфигурация всего сайта: навигация, редиректы, темы, SEO.
Основные секции docs.json:
  • navigation — структура боковой панели и локализация
  • redirects — редиректы
  • seo — мета-теги и поисковая оптимизация
  • colors — цвета темы
  • styling.codeblocks — темы подсветки кода
  • banner — баннер в верхней части сайта
Последнее изменение 21 июня 2026 г.