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

Руководство по стилю контента

Все уровни

Именно последовательность делает справочник заслуживающим доверия. Следуйте этим правилам, и ваш PR без труда пройдёт проверку.

Тон​

  • Ясно и прямо. Короткие предложения. Начинайте с сути.
  • Дружелюбно, но без воды. Уберите "в современном быстро меняющемся мире". Уважайте время читателя.
  • Принципиально, но честно. Сначала дайте один рекомендуемый способ, затем отметьте альтернативы и компромиссы.
  • Примеры важнее теории. Покажите фрагмент кода или конкретный случай; не просто описывайте.
  • Американский английский.

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

---
sidebar_position: 2
title: "Your Page Title"
description: "One sentence for search and previews."
---

<LevelBadge level="beginner" />

A one or two sentence intro that states what the reader will get.

## Sections with ## headings
...

## Next
- 2–4 links to related pages
  • Начинайте со значка уровня (beginner | intermediate | advanced | all). Компоненты глобальны — не импортируйте их.
  • Завершайте списком "Далее" / "Связанное" из 2–4 внутренних ссылок.
  • Используйте выноски (:::tip, :::warning, :::note, :::info) для акцентов, умеренно.

Два жёстких правила​

:::warning Не подлежит обсуждению

  1. Ссылайтесь на источники для изменчивых фактов. Имена моделей, цены, лимиты, точные флаги, бета-функции → сошлитесь на официальный источник и добавьте <VerifyNote lastVerified="YYYY-MM-DD" source="…">. Никогда не прописывайте факты о моделях жёстко — ссылайтесь на таблицу моделей. Подробности: Проверка фактов.
  2. Не выдумывайте. Никаких придуманных статистик, цитат, API или функций. Если не уверены — скажите об этом или поставьте пометку [verify]. :::

Мнение против официальной позиции​

  • Мы принципиальны — в этом наша ценность. Рекомендуйте, а не просто перечисляйте.
  • Но официальная документация — источник истины. Следуйте ей, ссылайтесь на неё и никогда не противоречьте ей молча.

Подводные камни MDX​

  • Фигурные скобки {like this} в прозе воспринимаются MDX как код — заключайте их в обратные кавычки или блоки кода, либо используйте [квадратные скобки] в примерах.
  • Тестируйте локально: npm run build должна проходить (она падает на сломанных ссылках).

Далее​