Про документацію

Як допомогти з документацією

Документація відкрита для спільноти: будь-хто може запропонувати правки через pull request.

Репозиторій: github.com/stvworlds/STVdocs

Короткий гайд

1. Відкрийте репозиторій і натисніть Fork (або створіть гілку, якщо маєте доступ).
2. Знайдіть потрібний .mdx файл у каталозі docs/ (або додайте новий).
3. Внесіть зміни. Правки можна зробити прямо на GitHub або локально після git clone.
4. Збережіть коміт і відкрийте Pull request у stvworlds/STVdocs.
5. Коротко опишіть, що змінили і навіщо. Після рев’ю зміни потраплять на сайт.

Поради

• Пишіть українською, стисло і зрозуміло.
• Одна PR — одна тема (правило, сервер, інструкція), так простіше перевірити.
• Перед PR перегляньте сусідні сторінки, щоб зберегти той самий тон і структуру.
• Якщо не впевнені у формулюванні — усе одно можна надіслати PR: краще чернетка, ніж відсутня інформація.

Як писати сторінки (Markdown / MDX)

Документація побудована на Fumadocs і використовує MDX — розширення Markdown із підтримкою компонентів.

Оригінальна довідка Fumadocs (англійською): fumadocs.dev/docs/markdown.

Нижче — скорочений гайд саме для наших сторінок у docs/.

MDX

MDX — це Markdown + JSX. Можна імпортувати компоненти й використовувати їх у тексті. Також підтримується GFM (GitHub Flavored Markdown).

Корисні посилання:

• Синтаксис MDX
• Специфікація GFM

Приклад базового синтаксису:

## Заголовок

### Підзаголовок

Привіт, **жирний**, _курсив_, ~~закреслений~~

1. Перший
2. Другий
3. Третій

- Пункт 1
- Пункт 2

> Цитата

![опис](/image.png)

| Таблиця | Опис   |
| ------- | ------ |
| Привіт  | Світ   |

Frontmatter

На початку кожного файлу — YAML-блок. Поле title стає заголовком сторінки (h1) у інтерфейсі.

---
title: Назва сторінки
description: Короткий опис для навігації та SEO
---

Текст сторінки…

Тому заголовок # (h1) у тілі сторінки зазвичай не потрібен — достатньо title у frontmatter і далі ##, ###.

Посилання

• Внутрішні посилання обробляються як навігація сайту (без повного перезавантаження).
• Зовнішні посилання відкриваються в новій вкладці з безпечними атрибутами.

[Текст посилання](https://example.com)

Також працює «голе» посилання: https://example.com

Картки (Cards)

Зручно для блоків із посиланнями.

<Cards>
  <Card href="/docs" title="Вступ">
    Початок роботи з документацією
  </Card>
  <Card title="Без посилання">
    `href` можна не вказувати
  </Card>
</Cards>

Живий приклад:

Виноски (Callout)

Підказки, попередження тощо. Типи:

• info (за замовчуванням)
• warn / warning
• error
• success
• idea

<Callout>Звичайна підказка</Callout>

<Callout title="Увага" type="warn">
  Важливе попередження
</Callout>

<Callout title="Помилка" type="error">
  Критична інформація
</Callout>

<Callout title="Ідея" type="idea">
  Корисна думка
</Callout>

Живий приклад:

Заголовки та зміст (TOC)

До кожного заголовка автоматично додається якір (якір: Привіт Світ → привіт-світ).

Керування змістом:

## Прихований у змісті [!toc]

Цей заголовок не потрапить у TOC.

## Лише в змісті [toc]

Цей пункт буде **тільки** в TOC (корисно для додаткових пунктів).

Власний якір:

## Мій розділ [#mij-rozdi]

## Розділ у TOC з власним id [toc] [#custom-id]

Посилання на розділ: /docs/about_docs#mij-rozdi.

Блоки коду

Підсвічування синтаксису працює за замовчуванням.

```js
console.log('Hello World');
```

```js title="Приклад"
console.log('Hello World');
```

Номери рядків

```ts lineNumbers
const a = 'Hello World';
console.log(a);
```

```js lineNumbers=4
function main() {
  console.log('починається з 4');
  return 0;
}
```

Shiki Transformers

Можна підсвічувати рядки, слова, показувати diff і focus:

```tsx
// підсвітити рядок
<div>Hello World</div> // [!code highlight]

// підсвітити слово
<div>Fumadocs</div>

// diff
console.log('hewwo'); // [!code --]
console.log('hello'); // [!code ++]

// focus
return new ResizeObserver(() => {}) // [!code focus]
```

Вкладки коду (tab)

Суміжні блоки з tab="…" збираються у вкладки:

```ts tab="Вкладка 1"
console.log('A');
```

```ts tab="Вкладка 2"
console.log('B');
```

Щоб синхронізувати кілька груп вкладок, на першому блоці додайте tab-group:

```ts tab="Вкладка 1" tab-group="my-group"
console.log('A');
```

```ts tab="Вкладка 2"
console.log('B');
```

Include (вставка файлу)

Доступно у Fumadocs MDX. Шлях відносний до поточного файлу:

<include>./another.mdx</include>

Команди npm

Мова npm у блоці коду розгортається у вкладки для різних пакетних менеджерів:

```npm
npm i next -D
```

Кроки (Steps)

Для покрокових інструкцій (якщо увімкнено remark-steps):

### Встановлення [step]

### Написати код [step]

### Деплой [step]

Інші компоненти

У MDX можна використовувати вбудовані компоненти Fumadocs UI (вкладки, акордеони, зображення тощо) — див. документацію компонентів.

Стиль наших сторінок

• Мова: українська.
• Frontmatter: обов’язково title, бажано description.
• Структура: короткі розділи ## / ###, списки замість довгих абзаців.
• Команди, IP і шляхи оформлюйте блоками коду (мови text або bash).
• Не копіюйте внутрішні посилання з сайту Fumadocs (/docs/mdx/...) — вони ведуть на їхній сайт, не на наш.
• Тримайте той самий тон, що на сусідніх сторінках (rules/, servers/, how_to_join).