> ## Documentation Index > Fetch the complete documentation index at: https://docs.ss14.art/llms.txt > Use this file to discover all available pages before exploring further. # Руководство по редактированию документации Привет! Как вы, возможно, заметили, этот сайт документации полностью открыт и доступен для редактирования на GitHub. Вы можете найти страницу этого сайта на GitHub по адресу [https://github.com/space-sorcerers/docs](https://github.com/space-sorcerers/docs). Есть несколько моментов, которые стоит учитывать при участии. Хотя мы запрещаем web-edit PR (сделанные исключительно на GitHub) в основные репозитории Space Station 14 и Robust Toolbox, здесь это не так. **Web-редактирование приветствуется**, чтобы сделать редактирование документации максимально безболезненным. Если вы хотите узнать, какие возможности доступны при написании документации, перейдите на [Пример страницы документации](./docs-example-page). ## Стиль Документация должна быть написана в [стиле технической коммуникации](https://ohiostate.pressbooks.pub/feptechcomm/chapter/3-writing-style/). Эффективная техническая коммуникация должна быть [краткой, точной, прямой и хорошо организованной](https://ohiostate.pressbooks.pub/feptechcomm/chapter/3-writing-style/), написана соответствующим [голосом и тоном](https://ohiostate.pressbooks.pub/feptechcomm/chapter/3-1-voice-tone/) с использованием [правильной грамматики и пунктуации](https://ohiostate.pressbooks.pub/feptechcomm/chapter/3-2-mechanics-grammar/), со ссылками на соответствующие источники при необходимости. ## Быстрые правки через GitHub Если вы хотите просто внести небольшую правку в страницу, выполните следующие шаги — вам не понадобится ничего из описанного далее: 1. Создайте аккаунт на GitHub или войдите, если он уже есть. 2. Сделайте fork репозитория [space-sorcerers/docs](https://github.com/space-sorcerers/docs) на GitHub. 3. Нажмите на иконку «View & Edit Page on GitHub» в правом верхнем углу любой страницы этого сайта. 4. Нажмите кнопку «Edit this file» в правом верхнем углу просмотра файла. 5. Внесите изменения, затем сделайте commit и создайте pull request! Мы сделаем всё остальное. ## Локальная сборка ### Установка Требуется Node.js v20.17.0 или новее. Установите CLI Mintlify глобально: ```bash theme={null} npm i -g mint ``` ### Запуск dev-сервера Из корня проекта: ```bash theme={null} mint dev ``` Откроется локальный предпросмотр по адресу `http://localhost:3000` с горячей перезагрузкой при изменении файлов. ### Проверка на ошибки ```bash theme={null} npx mintlify validate ``` Проверяет синтаксис всех `.mdx` файлов и навигацию. Запускается в CI при каждом PR. ### Обновление CLI ```bash theme={null} mint update ``` ### Форматирование Для подсветки синтаксиса и форматирования MDX-файлов используйте расширения: * **VS Code / Cursor**: [MDX](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) + [Prettier](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode) ## Проверка изменений Если вы создали PR, проще всего проверить изменения во вкладке «Files changed» в GitHub. Также можно использовать локальное расширение для предпросмотра markdown, например, для [VSCode](https://marketplace.visualstudio.com/items?itemName=shd101wyy.markdown-preview-enhanced). Для аутентичного предпросмотра каждый PR будет автоматически развёрнут через Mintlify preview. Ссылку можно найти в разделе проверок PR. ## Ревью Мейнтейнеры будут проверять pull request для документации на содержание и [стиль](#style). Мейнтейнеры понимают, что многие участники не являются носителями языка, и будут полезны в своих комментариях к ревью. Чтобы максимально эффективно использовать время мейнтейнеров, перед отправкой, пожалуйста: * Вычитайте свои изменения * Используйте проверку орфографии * Рассмотрите использование инструментов проверки грамматики, таких как [Grammarly](https://www.grammarly.com/) ## Синтаксис MDX Мы используем **MDX** — Markdown с возможностью встраивать JSX-компоненты. Ниже — основные конструкции. ### Заголовки ```mdx theme={null} ## Заголовок секции ### Подзаголовок #### Подподзаголовок ``` #### Пользовательские ID ```mdx theme={null} ## Моя секция {#custom-anchor} ``` Ссылка: `#custom-anchor`. #### Отключение привязки ```mdx theme={null}

Заголовок без якоря

``` ### Форматирование текста | Стиль | Синтаксис | Результат | | --------------- | ------------------ | ------------------------- | | **Жирный** | `**текст**` | **жирный текст** | | *Курсив* | `_текст_` | *курсив* | | ~~Зачёркнутый~~ | `~текст~` | ~~зачёркнутый~~ | | Верхний индекс | `текст` | обычныйверхний | | Нижний индекс | `текст` | обычныйнижний | ### Ссылки ```mdx theme={null} [Внутренняя страница](/ru/meta/guide-to-editing-docs) [Внешний ресурс](https://example.com) ``` ### Блочные цитаты ```mdx theme={null} > Это цитата. > > Второй абзац цитаты. ``` ### Разделители ```mdx theme={null} --- ``` ### Переносы строк ```mdx theme={null} Строка до.
Строка после. ``` ### Комментарии MDX ```mdx theme={null} {/* Это комментарий — он не попадёт в собранную страницу */} ``` HTML-комментарии `` в MDX не работают. Используйте `{/* */}`. ### Экранирование специальных символов В MDX фигурные скобки (`{}`) и угловые скобки (`<>`) имеют специальное значение. Чтобы вывести их как обычный текст, оберните в обратные кавычки или используйте HTML-сущности: ```mdx theme={null} Синтаксис `{variable}` для подстановки значений. Стрелочка `->` — это не JSX. ``` ### Математические выражения Строчные: `$E = mc^2$` Блочные: ```mdx theme={null} $$ E = mc^2 $$ ``` ## Таблицы ```mdx theme={null} | Свойство | Тип | Описание | | -------- | ------- | ----------------- | | Name | `string`| Имя пользователя | | Age | `int` | Возраст | ``` Выравнивание столбцов: ```mdx theme={null} | По левую | По центру | По правую | | :------- | :-------: | --------: | | left | center | right | ``` ## Списки ```mdx theme={null} 1. Первый пункт 2. Второй пункт - Вложенный пункт - Ещё вложенный 3. Третий пункт ``` ## Изображения ```mdx theme={null} ![Описание изображения](/images/example.png) ``` С тёмной/светлой темой: ```html theme={null} Светлая тема Тёмная тема ``` ## Блоки кода ### Обычный блок ````mdx theme={null} ```csharp public sealed class GreeterSystem : EntitySystem { public void GreetEveryone(string message) { Logger.Info(message); } } ``` ```` ### С заголовком ````mdx theme={null} ```csharp GreeterSystem.cs public void GreetEveryone(string message) ``` ```` ### С иконкой ````mdx theme={null} ```yaml icon=file-yaml - type: Greeter message: "Hello!" ``` ```` ### Подсветка строк ````mdx theme={null} ```csharp highlight={1,3-5} public sealed class GreeterSystem : EntitySystem { public void GreetEveryone(string message) { Logger.Info(message); } } ``` ```` ### Фокус на строках ````mdx theme={null} ```csharp focus={2,4} public sealed class GreeterSystem : EntitySystem { public void GreetEveryone(string message) { Logger.Info(message); } } ``` ```` ### Номера строк ````mdx theme={null} ```csharp lines public void GreetEveryone(string message) { Logger.Info(message); } ``` ```` ### Сворачиваемый блок ````mdx theme={null} ```csharp expandable // Длинный код, который можно свернуть Console.WriteLine("Hello!"); ``` ```` ### Перенос строк ````mdx theme={null} ```csharp wrap var message = "This is a very long line of code that will wrap to the next line instead of scrolling horizontally."; ``` ```` ### Дифф (различия) ````mdx theme={null} ```csharp lines public void OldMethod() // [!code --] public void NewMethod() // [!code ++] ``` ```` ### Группы кода (CodeGroup) Синхронизируются по заголовкам с другими CodeGroup и Tabs на странице: ````mdx theme={null} ```csharp Greeter.cs Console.WriteLine("Hello!"); ``` ```python greeter.py print("Hello!") ``` ```bash greeter.sh echo "Hello!" ``` ```` Для выпадающего списка вместо вкладок: ```mdx theme={null} ... ``` ## Компоненты Mintlify ### Callouts ```mdx theme={null} Примечание Информация Совет Предупреждение Опасность Готово ``` Кастомный: ```mdx theme={null} Произвольный callout ``` ### Accordion ```mdx theme={null} Скрытое содержимое. ``` Группа: ```mdx theme={null} ... ... ``` ### Badge ```mdx theme={null} Обычный Готово Beta Избранное ``` ### Cards ```mdx theme={null} Описание карточки. Компактный вариант. ``` ### Columns ```mdx theme={null} ... ... ``` ### Frame (для изображений) ```mdx theme={null} Описание ``` ### Icons ```mdx theme={null} ``` ### Steps ```mdx theme={null} Инструкция для первого шага. Инструкция для второго шага. ``` ### Tabs ```mdx theme={null} Инструкция для Windows. Инструкция для Linux. ``` Вкладки с одинаковыми названиями синхронизируются по всей странице. ### Tiles ```mdx theme={null} Tile preview ``` ### Tooltip ```mdx theme={null} термин ``` ### Tree (файловая структура) ```mdx theme={null} ``` ### Mermaid (диаграммы) ````mdx theme={null} ```mermaid graph TD; A-->B; A-->C; B-->D; C-->D; ``` ```` С ELK-рендерингом: ````mdx theme={null} ```mermaid %%{init: {'flowchart': {'defaultRenderer': 'elk'}}}%% flowchart LR A[Start] --> B[Process] B --> C[End] ``` ```` ### Visibility (показывать разный контент людям и AI) ```mdx theme={null} Видно только в браузере. Видно только AI-агентам в Markdown-экспорте. ``` ## Переиспользуемые сниппеты Создайте файл в `/snippets/` и импортируйте его на любую страницу: ```mdx theme={null} import SetupGuide from "/snippets/setup-guide.mdx"; ``` С переменными: ```mdx theme={null} import InstallSnippet from "/snippets/install.mdx"; ``` ## Frontmatter (YAML-шапка) Каждый `.mdx` файл начинается с `---`: ```yaml theme={null} --- title: "Название страницы" description: "Описание для поисковиков и превью" sidebar_position: 5 --- ``` Полезные поля: | Поле | Описание | | ------------------ | ---------------------------------- | | `title` | Заголовок страницы | | `description` | Описание (SEO, превью) | | `sidebar_position` | Порядок в боковой панели | | `noindex` | `true` — скрыть от поисковиков | | `canonical` | Канонический URL | | `og:title` | Свой заголовок для соцсетей | | `og:image` | Своя картинка для превью | | `boost` | Приоритет в поиске (1.0 = обычный) | | `groups` | Доступно только указанным группам | | `draft` | `true` — черновик, не публикуется | ## SEO и мета-теги Глобальные мета-теги задаются в `docs.json`: ```json theme={null} "seo": { "metatags": { "og:image": "https://docs.ss14.art/images/og.png", "google-site-verification": "..." } } ``` ### Канонические URL ```json theme={null} "seo": { "metatags": { "canonical": "https://docs.ss14.art" } } ``` ### OG-изображения По умолчанию Mintlify генерирует OG-картинку автоматически. Можно задать фоновое изображение: ```json theme={null} "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`: ```json theme={null} "redirects": [ { "source": "/old/path", "destination": "/new/path" } ] ``` С wildcard: ```json theme={null} "redirects": [ { "source": "/ru/:slug*", "destination": "/en/:slug*" } ] ``` ## Поиск ### Boost (приоритет страницы) В frontmatter страницы: ```yaml theme={null} --- boost: 3 --- ``` Или для целой группы в `docs.json`: ```json theme={null} { "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` — баннер в верхней части сайта