Перейти к содержанию

Руководство по разработке документации

Документация OpenCS разработана с использованием Material for MkDocs. Исходные тексты хранятся в формате Markdown.

Сайт размещён на сервере debian-13-6 (IP: 100.126.95.93), и с ним можно комфортно работать с любых ПК в вашей сети Tailscale или локальной сети.

Вариант 1: Работа через Git (Рекомендуемый)

На сервере настроен Git-репозиторий с автоматической пересборкой сайта при каждом git push.

1. Клонирование на ваш рабочий ПК (ноутбук/десктоп)

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

# Клонирование через сеть Tailscale:
git clone palex@100.126.95.93:/home/palex/opencs-docs.git

# Или по имени MagicDNS:
git clone palex@debian-13-6:/home/palex/opencs-docs.git

2. Редактирование

Откройте папку в VS Code, Cursor, Obsidian или любом текстовом редакторе. Все страницы лежат в каталоге docs/. Структура меню задаётся в файле mkdocs.yml.

3. Публикация изменений

После внесения правок сделайте коммит и отправьте изменения на сервер:

git add .
git commit -m "Обновлено описание модуля огнестойкости"
git push

Сайт на сервере автоматически пересоберётся за 1-2 секунды! Результат сразу будет виден по адресу http://debian-13-6:8081.

Вариант 2: Прямое редактирование через VS Code (Remote - SSH)

Если вы не хотите клонировать репозиторий на рабочий ПК, а хотите редактировать файлы прямо на сервере:

  1. Установите в VS Code официальное расширение Remote - SSH.
  2. Нажмите ++f1++ и выберите Remote-SSH: Connect to Host...
  3. Введите palex@100.126.95.93 (или palex@debian-13-6).
  4. Откройте папку /home/palex/opencs-docs.
  5. Редактируйте файлы. Чтобы обновить сайт, откройте встроенный терминал в VS Code и выполните: 
    ./build.sh

Поддержка формул и схем

  • Формулы LaTeX: оборачиваются в $...$ для строчных или $$...$$ для выносных формул (обрабатываются MathJax).
  • Диаграммы Mermaid: блоки с кодом ```mermaid.
  • Блоки внимания: синтаксис !!! note "Заголовок" или > [!NOTE].