Изменения в базе знаний MeshWorks

Спасибо, что помогаете развивать MeshWorks Wiki!
Этот документ объясняет, как быстро внести правки в контент и что нужно проверить перед Pull Request.

1. Как работать с репозиторием​

Через интерфейс GitHub (самый простой)​

Этот вариант подойдёт, если нужно поправить текст, ссылку или картинку и не хочется настраивать окружение локально.

1. Откройте нужную страницу на https://wiki.meshworks.ru и нажмите «Отредактировать эту страницу».
2. GitHub откроет исходный файл и предложит создать ветку и Pull Request.
3. Внесите правки, напишите краткое описание изменений и отправьте PR.

Локально (для более крупных изменений)​

Если вы планируете несколько связанных правок, новые страницы или разделы, удобнее работать локально.

1. Клонируйте репозиторий и установите зависимости:

   npm ci
   npm start
   

2. Работайте в новой ветке (feature/my-topic).
3. Проверяйте изменения на http://localhost:3000/.
4. Перед пушем выполните npm run check — это та же проверка, что крутится в CI.

Дальше шаги одинаковые для обоих вариантов: вы редактируете файлы, описанные ниже, и отправляете Pull Request.

2. Как устроены страницы​

• Шапка страницы (front matter): в начале каждого файла есть блок между ---. В нём минимум такие поля:

  ---
  title: Название вверху страницы
  description: "Краткое SEO-описание страницы (1–2 предложения)"
  slug: /путь/в/адресной/строке
  sidebar_label: Как элемент называется в меню
  sidebar_position: Порядок в меню (число, например 3)
  ---
  

• description должен быть человекочитаемым описанием страницы (1–2 предложения), соответствовать содержимому и нормально смотреться как сниппет в поиске.
• Структура: docs/<section>/<page>.mdx. Используйте осмысленные директории (devices/ready-made/portable.md и т.д.).
• Язык: русский, единый стиль (повествовательный, без жаргона).

3. Что вы хотите сделать​

Изменить существующую страницу​

1. Найдите исходный файл в docs/... или static-pages/... (через кнопку «Отредактировать эту страницу» в интерфейсе вики или напрямую в редакторе GitHub, если работаете локально — см. раздел 1).
2. Внесите правки в текст.
3. Не меняйте slug, если адрес страницы должен остаться прежним (чтобы не ломать существующие ссылки).
4. При необходимости обновите title, description и sidebar_label, чтобы они лучше отражали содержимое.

Добавить новую страницу в существующий раздел​

1. Выберите папку раздела, например:
   • docs/node-setup/
   • docs/devices/ready-made/
2. Создайте новый файл:
   • если на странице будет только текст и обычный Markdown — new-topic.md;
   • если нужны компоненты Docusaurus (например, <IdealImage>, <Link> и т.п.) — new-topic.mdx. В начале файла добавьте блок --- (front matter) по образцу из раздела 2 или просто скопируйте его из ближайшей страницы и замените значения.
3. Задайте:
   • slug — человекочитаемый путь, например /devices/ready-made/new-board;
   • sidebar_label — короткое название в меню;
   • sidebar_position — число, задающее порядок внутри раздела (можно использовать дробные значения, например 2.5).
4. В тексте страницы дайте понятный заголовок и 1–2 вводных абзаца — это помогает и людям, и поисковикам.

Добавить новый раздел​

1. Создайте папку docs/<section>/, например docs/monitoring/.
2. Внутри заведите главную страницу раздела index.mdx с front matter вида:

---
slug: /monitoring
 title: Мониторинг
 description: "Общий раздел о мониторинге и алертах для MeshWorks."
 sidebar_label: Мониторинг
 sidebar_position: 5
 ---

3. Дополнительные страницы раздела кладите в ту же папку: docs/monitoring/alerts.md, docs/monitoring/dashboards.mdx и т.п.
4. Если нужен отдельный подпункт в сайдбаре для вложенной группы (как USB-драйверы внутри node-setup), используйте _category_.json в подпапке, по аналогии с docs/node-setup/serial-drivers/_category_.json.

4. Оформление текста​

• Фишки (admonitions): можно вставлять цветные блоки, чтобы выделить мысль:

  :::tip
  Подсказка или полезный совет.
  :::
  
  :::favorite
  Для важных сообщений, например предупреждения о партнёрских ссылках или особых условиях.
  :::
  

  Аналогично работают :::info, :::warning, :::note и т.д.

Изображения​

• Кладите файлы в static/img/<topic>/ и ссылайтесь как <IdealImage img={require('@site/static/img/<topic>/image.png')} alt="alt" className="docImage" />.
• Используйте web-friendly размеры (ширина ≤ 1600px) и сжимайте PNG/JPG перед коммитом.
• Если заменяете изображение, убедитесь, что оно не переиспользуется в других страницах (rg -l filename.png).

Ссылки и код​

• Внешние ссылки лучше открывать в новой вкладке: <a href="..." target="_blank" rel="noreferrer noopener">. Если не хочется писать HTML, используйте компонент Link из Docusaurus.
• Названия команд и файлов обрамляем обратными кавычками (символ ` рядом с клавишей Esc). Пример: `meshtastic --help`.
• Длинные примеры оформляем тройными кавычками с указанием языка:

  ```bash
  meshtastic --help
  ```
  

5. Проверки перед Pull Request​

• npm run check (линт + build) успешно завершился.
• Новые изображения лежат в static/img/... и упомянуты в git.
• Во фронтматтере указаны slug/labels и осмысленный description, нет GUID или автогенерируемых ссылок.
• Ссылки проверены вручную, особенно на внешний контент.
• В PR-описании перечислены ключевые изменения.

6. Шаблоны, если хотите завести Issue​

• Хочется новую страницу или раздел? Создайте в репе Issue по шаблону Предложение.
• Для багов (опечатка, 404, дубли) используйте шаблон Баг.

7. Лицензия​

• Репозиторий распространяется под CC BY-SA 4.0; русскоязычное описание — в LICENSE.ru.md.