Работа с сайтом docs.reversi.tech

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

Коротко

Docusaurus превращает папку с документацией в сайт. В этом репозитории статьи находятся в docs, порядок разделов задаётся в _category_.json, а порядок статей внутри раздела — полем sidebar_position в начале Markdown-файла. Разделы самостоятельны и не образуют обязательной общей последовательности.

Зачем это нужно

Когда база знаний растёт, важно править её как инженерный проект. Нельзя просто заменить один абзац и не посмотреть соседние статьи того же раздела: новый текст может использовать термин, который внутри методички ещё не объяснялся, или повторять следующую статью. Нельзя добавить картинку в случайную папку: через месяц будет трудно понять, к какой статье она относится.

Работа с сайтом сводится к понятному циклу:

прочитать раздел -> поправить Markdown и изображения -> проверить сайт -> сохранить изменение в Git

Такой порядок помогает держать каждый раздел внутренне последовательным. Сначала автор понимает место статьи в своей методичке, затем вносит ограниченную правку, после этого проверяет сборку и только потом фиксирует результат.

Как устроен репозиторий

В корне проекта лежат файлы Docusaurus и настройки сборки. Для методической работы чаще всего нужны такие части:

Путь	Что там находится	Когда открывать
docs/	все учебные разделы и статьи	при любой правке содержания базы знаний
docs/<razdel>/_category_.json	название, позиция и описание раздела	когда меняется порядок или описание раздела
docs/<razdel>/<statya>.md	текст конкретной статьи	когда меняется методика, примеры, код или ссылки
docs/<razdel>/img/<statya>/	изображения конкретной статьи	когда добавляются шапки, схемы, фото и коллажи
README.md	команды запуска и проверки сайта	перед локальным запуском или настройкой компьютера
sidebars.ts	правило сборки боковой навигации	обычно только для проверки общей логики сайта
docusaurus.config.ts	настройки сайта, темы, ссылок и поиска	когда меняется поведение всего сайта

В этом проекте боковое меню строится автоматически. Поэтому новый файл в docs становится частью навигации, если он лежит в нужной папке и содержит корректные служебные поля.

Служебный блок статьи

В начале каждой статьи находится frontmatter — блок между строками ---. Он не показывается как обычный текст, но нужен сайту.

---
title: "Arduino IDE: первый проект и загрузка скетча"
sidebar_position: 2
description: "Краткое описание статьи для страницы и поиска."
image: "img/arduino-ide/1.png"
---

Поле	Для чего нужно	Как заполнять
title	название страницы и вкладки	коротко и буквально, без лишних украшений
sidebar_position	место статьи в разделе	целым числом по внутренней последовательности
description	описание для индекса и предпросмотра	одним предложением о результате статьи
image	изображение для страницы и предпросмотра	относительным путём к картинке статьи

После frontmatter обычно повторяется заголовок первого уровня # ... и ставится заголовочное изображение. Это делает страницу понятной и в навигации, и при отдельном открытии.

Работа с изображениями

Для статьи удобно создавать отдельную папку:

docs/instrumenty-dlya-raboty/img/rabota-s-sajtom/
└── 1.png

В тексте картинку подключают относительным путём:

![Схема работы с документацией сайта](img/rabota-s-sajtom/1.png)

Для этой базы знаний есть несколько практических правил:

Тип изображения	Что важно проверить
заголовочная картинка	стиль совпадает с соседними статьями раздела, на ней нет мелкого текста
схема	стрелки попадают в объекты, подписи не наезжают на линии и блоки
реальное фото детали	видно именно обсуждаемый модуль, фон не мешает восприятию
коллаж	элементы достаточно крупные, подписи не спорят с изображением
скриншот симулятора	схема читается, провода и компоненты различимы

Если статья говорит о реальном датчике, моторе, плате или модуле связи, одной абстрактной схемы обычно недостаточно. Нужны реальные примеры устройств, а рядом — короткая таблица с характеристиками, по которым ученик понимает различия.

Последовательность методики

При правке учебной статьи сначала проверьте соседние материалы того же раздела. Новая статья не должна требовать знания, которое появляется только дальше внутри этой методички. Если без такого знания не обойтись, лучше добавить короткое объяснение или перенести пример в более позднюю статью раздела. Порядок статей из других разделов при этом не считается обязательным.

Хорошая проверка перед правкой:

1. Откройте текущую статью.
2. Откройте предыдущую и следующую статьи раздела.
3. Найдите термины, библиотеки, конструкции кода и элементы схем.
4. Убедитесь, что всё новое уже объяснено ранее или объясняется в этой статье.
5. После правки перечитайте практические задания и вопросы самопроверки.

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

Локальный запуск

Сайт запускается локально через Node.js 20+. Если Node.js установлен в системе, используйте:

npm ci
npm run start -- --host 127.0.0.1 --port 3000

Если для проекта используется локальный Node из ~/.cache/codex-node/node-v20, команды запускают с добавлением пути:

PATH="$HOME/.cache/codex-node/node-v20/bin:$PATH" npm ci
PATH="$HOME/.cache/codex-node/node-v20/bin:$PATH" npm run start -- --host 127.0.0.1 --port 3000

После запуска откройте в браузере:

http://127.0.0.1:3000

Режим разработки удобен для чтения и визуальной проверки: страница обновляется после изменения файлов. Но успешный запуск dev-сервера ещё не заменяет сборку.

Проверка перед сохранением

Перед тем как считать правку готовой, выполните проверки из README:

npm run typecheck
npm run build

Если используется локальный Node:

PATH="$HOME/.cache/codex-node/node-v20/bin:$PATH" npm run typecheck
PATH="$HOME/.cache/codex-node/node-v20/bin:$PATH" npm run build

typecheck проверяет TypeScript-часть проекта. build собирает статический сайт и часто находит проблемы, которые незаметны при обычном чтении: битую ссылку, ошибку MDX, некорректный импорт или неверный путь к изображению.

Что не добавлять в Git

В репозиторий должны попадать исходные материалы базы знаний, а не результаты локальной работы инструментов. Обычно не коммитят:

• node_modules;
• build;
• .docusaurus;
• .npm-cache;
• файлы .env и другие секреты;
• временные архивы, черновые выгрузки и служебные файлы редактора.

Большая часть этих путей уже перечислена в .gitignore. Но перед коммитом всё равно нужно смотреть git status и git diff --staged: файл мог оказаться новым, переименованным или лежать вне привычной папки.

Как связаны инструменты раздела

Инструмент	Роль в этой базе знаний
Git	сохраняет историю правок статей, кода, схем и изображений
Arduino IDE	помогает быстро проверить первые скетчи на реальной плате
Tinkercad	даёт безопасную виртуальную проверку простых схем и входов-выходов
VS Code	удобен для правки Markdown, поиска по репозиторию и работы с терминалом
PlatformIO	нужен для более крупных проектов прошивок с зависимостями и несколькими файлами
ИИ-помощник	помогает составить черновик, найти противоречия и подготовить проверочный список

Эти инструменты не заменяют друг друга. Например, ИИ может предложить объяснение, VS Code помогает аккуратно внести текст, Docusaurus показывает страницу, а Git сохраняет проверенную версию.

Что запомнить о работе с сайтом

• Основной учебный контент находится в docs.
• Порядок разделов задаётся в _category_.json, порядок статей внутри раздела — через sidebar_position.
• Картинки лучше хранить рядом со статьёй, в папке img/<statya>/.
• Перед правкой нужно читать соседние статьи того же раздела, чтобы сохранить внутреннюю последовательность методички.
• Для проверки сайта используйте npm run typecheck и npm run build.
• В Git сохраняют исходники базы знаний, а не локальные результаты сборки и зависимости.

Практика

Задание 1. Найдите место статьи

Выберите любой раздел. Откройте _category_.json, затем три соседние статьи. Определите, какая статья идёт раньше, какая позже и какое знание связывает их внутри этой методички.

Задание 2. Проверьте изображение

Откройте статью с несколькими картинками. Для каждой картинки запишите её путь, роль в статье и одну возможную проблему читаемости: мелкий текст, пересечение стрелок, неясная подпись или плохая связь с абзацем.

Задание 3. Соберите сайт

Запустите локальную сборку. Если сборка завершилась успешно, найдите изменённую страницу в браузере. Если появилась ошибка, определите, относится ли она к ссылке, изображению, MDX-синтаксису или TypeScript.

Проверьте себя

• Где находятся статьи базы знаний?
• Чем _category_.json отличается от frontmatter отдельной статьи?
• Почему после правки текста нужно смотреть соседние статьи того же раздела?
• Какой путь удобен для хранения изображений конкретной статьи?
• Чем локальный dev-сервер отличается от команды npm run build?
• Какие файлы не должны попадать в Git?

Ориентиры для самопроверки

Сначала ответьте без подсказки. Ответ можно считать полным, если вы:

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

Если один из пунктов объяснить не получается, найдите соответствующую главу статьи, перечитайте её и повторите ответ.

Словарь статьи

• Docusaurus — генератор документационных сайтов на основе React и Markdown/MDX.
• Markdown — текстовый формат разметки для заголовков, списков, таблиц, ссылок и изображений.
• MDX — расширение Markdown, позволяющее использовать React-компоненты внутри страниц.
• Frontmatter — служебный блок в начале файла с метаданными страницы.
• Sidebar — боковая навигация раздела.
• Dev-сервер — локальный сервер для просмотра сайта во время разработки.
• Статическая сборка — готовая версия сайта, которую можно разместить на хостинге.

Связанные темы

• Git: история и аккуратная работа с изменениями — как сохранять проверенные правки документации.
• Visual Studio Code и PlatformIO: среда для больших проектов — как работать с файлами, поиском и терминалом.
• ИИ-помощники и GPT: учимся думать вместе с моделью — как использовать помощника для методической проверки без потери ответственности.

Источники

• Docusaurus. Docs Introduction: https://docusaurus.io/docs
• Docusaurus. Markdown Features: https://docusaurus.io/docs/markdown-features
• Docusaurus. Docs Sidebar: https://docusaurus.io/docs/sidebar