Стандарт работы с системой документации

Версия: 1.2
Дата: 21.04.2026
Статус: Утверждён

Этот документ — единый свод правил организации, хранения, редактирования и публикации документации. Действует для всех проектов в системе.

⚠ СИСТЕМА ПРЕДНАЗНАЧЕНА ДЛЯ ЛОКАЛЬНОГО ИСПОЛЬЗОВАНИЯ

Система изначально и полностью спроектирована для работы на вашей локальной машине или закрытом сервере:

CMS-редактор работает только локально — требует npx decap-server на свободном порту (например 8083)
Git-репозиторий хранится локально — cms-config.json с хэшами паролей и _project_.json с полем access безопасно хранить в git
Просмотр — tools/serve_preview.sh запускает сайт на localhost
Деплой — опционален, сайт прекрасно работает без него

Что означает "локальное использование": Вы редактируете документы через браузерную CMS-админку или вручную, делаете git commit, смотрите результат на localhost. Это полный и самодостаточный рабочий процесс.

Если вам нужен публичный сервер: Выполните настройку деплоя — см. разделы "Деплой: Shared хостинг" и "Деплой: VPS". Это дополнительный слой, а не обязательное условие.

Если вы переводите репозиторий в публичный git (GitHub, GitLab, Bitbucket): До первого push добавьте в .gitignore:

cms-config.json

И в каждом _project_.json убрать поле access из коммита — хэши паролей в публичном репозитории позволяют их перебор офлайн.

Настройка Git-репозитория

При инициализации нового репозитория — выполнить один раз:

git init
git branch -m master main        # ветка обязательно main — CMS работает только с ней
git config core.ignorecase false  # Linux различает регистр — git должен тоже
git config user.email "your@email.com"
git config user.name "Your Name"

.gitignore должен содержать:

exports/
.deploy-tmp/
docs/_uploads/
# cms-config.json  ← раскомментировать при переводе в публичный git

Настройка `cms-config.json`

Единственный файл глобальных настроек. Находится в корне репозитория. Все скрипты и docusaurus.config.ts читают его — менять значения нужно только здесь.

{
  "admin": {
    "username": "alex",
    "password_hash": "$6$соль$хэш"
  },
  "site": {
    "title": "Название сайта",
    "url": "http://localhost"
  },
  "shared": {
    "deploy_path": "/home/username/public_html",
    "ssh_host": "username@shared.yourdomain.com",
    "ssh_port": 22
  },
  "vps": {
    "domain": "docs.yourdomain.com",
    "ssh_host": "user@docs.yourdomain.com",
    "ssh_port": 22,
    "remote_path": "/var/www/docs",
    "pm2_app": "docs"
  }
}

Поле	Назначение	Для локальной работы
`admin.username`	Логин admin для CMS и защищённых проектов	Обязательно заполнить
`admin.password_hash`	SHA-512 хэш — генерировать через `tools/add_user.sh --admin`	Обязательно заполнить
`site.title`	Название сайта — подставляется в `docusaurus.config.ts` и navbar	Заполнить
`site.url`	URL сайта — `http://localhost` для локальной работы, домен для деплоя	`http://localhost`
`shared.deploy_path`	Абсолютный путь к `public_html` на сервере	Только для деплоя
`shared.ssh_host`	`user@host` для SSH-подключения к shared хостингу	Только для деплоя
`shared.ssh_port`	SSH порт	Только для деплоя
`vps.domain`	Домен сайта на VPS	Только для деплоя
`vps.ssh_host`	`user@host` для SSH-подключения к VPS	Только для деплоя
`vps.ssh_port`	SSH порт	Только для деплоя
`vps.remote_path`	Корневой путь проекта на сервере — сборка в `remote_path/build/`	Только для деплоя
`vps.pm2_app`	Имя приложения в pm2	Только для деплоя

Секции shared и vps нужны только при деплое. Для локальной работы достаточно admin и site.

Настройка `docusaurus.config.ts`

Файл читает site.title и site.url из cms-config.json автоматически при каждой сборке. Не менять url и title в этом файле вручную — изменения перезапишутся.

Для смены названия или URL:

# Отредактировать cms-config.json → site.title / site.url
# Затем пересобрать:
npm run build

Для локальной работы site.url = "http://localhost" — это нормально, canonical URL и sitemap будут указывать на localhost, что не влияет на просмотр.

Концепция: единый поток

Все взаимодействия с документацией сходятся в одном месте — ветке main Git-репозитория. Это единственный источник правды.

Редактирование (CMS-админка)  ─┐
Редактирование (ИИ-агент)     ─┼──→  Git main  ──→  Сайт (сборка / деплой)
Редактирование (файлы руками) ─┘         │
                                          └──→  Экспорт (bundle по проекту)

Никакого параллельного хранения. Нет "актуальной версии на диске" отдельно от Git.

Потоки работы

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

Три равнозначных способа — все пишут в одни и те же файлы:

CMS-админка (/admin) — браузерный визуальный редактор, коммит при сохранении. Требует запущенного npx decap-server.
ИИ-агент — прямое редактирование файлов или через MCP-сервер DocMap
Вручную — редактор кода, после git add + git commit

Результат любого из трёх — коммит в main.

2. Хранение

Git ветка main — одна на всю систему. Несколько проектов живут в одной ветке в разных папках. Ветки не плодятся под проекты — это хаос. Для входящих документов от других — ветки import/* временно, до merge в main.

3. Локальный просмотр

npm run start                  # dev-сервер с hot reload, черновики видны
tools/serve_preview.sh 5000    # продакшн-сборка, черновики НЕ видны — как на деплое

Что где работает:

URL	Режим	Просмотр документов	CMS `/admin`
`http://localhost:3000`	dev (`npm run start`)	✅ с hot reload	✅ работает через `/admin/index.html`
`http://localhost:5000`	prod (`serve_preview.sh`)	✅ без черновиков	✅ работает

Для работы с CMS-редактором нужны оба процесса одновременно:

# Терминал 1 — прокси для git-операций CMS:
PORT=8083 npx decap-server

# Терминал 2 — сайт (dev или prod):
npm start                      # dev, порт 3000
# или
tools/serve_preview.sh 5000    # prod без черновиков, порт 5000

Открывай CMS по прямому URL с index.html:

http://localhost:3000/admin/index.html — через dev-сервер
http://localhost:5000/admin/index.html — через prod

⚠ Не открывай /admin/ без index.html — Docusaurus может отдать закешированную страницу вместо CMS.

Логин/пароль из cms-config.json → admin.

4. Деплой на сервер

Опциональный шаг. См. разделы "Деплой: Shared хостинг" и "Деплой: VPS".

5. Экспорт

Один проект — одна команда. Забирается ровно папка проекта без данных доступа:

tools/export_project.sh vitiana-api-platform

Стандарт структуры папок

Эталон

docs/
  <project-slug>/
    │
    ├── _project_.json     ← ОБЯЗАТЕЛЕН. Машиночитаемый маркер проекта.
    ├── assets/            ← ОБЯЗАТЕЛЕН (может быть пустым). Всё медиа проекта.
    ├── index.md           ← ОБЯЗАТЕЛЕН. Генерируется скриптом build_project_index.sh.
    │
    ├── overview/          ← Зачем существует проект. Контекст, архитектура, ключевые решения.
    │   └── _category_.json
    ├── reference/         ← Точные спецификации. Схемы, контракты, конфиги, API.
    │   └── _category_.json
    ├── operations/        ← Как запускать, деплоить, обслуживать, чинить.
    │   └── _category_.json
    └── development/       ← Роадмап, ADR, планы, история изменений.
        └── _category_.json

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

Правила именования

Имя папки проекта и всех вложенных папок — технический slug: строчные буквы, цифры, дефис. Без пробелов, без кириллицы.

✅  vitiana-api-platform
❌  Vitiana API
❌  раздел-1

Человекочитаемое название — только в _project_.json → label или _category_.json → label.

Правила определения названий

Уровень	Конфиг	Без конфига
Папка проекта	`_project_.json` → `label`	папка игнорируется как проект
Раздел	`_category_.json` → `label`	имя папки как есть
Документ	frontmatter `title:`	имя файла без расширения

Файл `_project_.json`

{
  "label": "Человекочитаемое название проекта",
  "description": "Краткое описание одной строкой",
  "version": "1.0",
  "public": false,
  "position": 1,
  "access": [
    {
      "username": "ivan",
      "password_hash": "$6$соль$хэш",
      "cms_hash": "sha256-хэш-от-ivan:password"
    }
  ]
}

Поле	Назначение	Обязателен
`label`	Название на главной и в сайдбаре	Да
`description`	Описание под названием на главной	Нет
`version`	Версия документации	Нет
`public`	Видимость на главной и в публичном экспорте	Да
`position`	Порядок на главной (1 = первый)	Нет
`access`	Список читателей с хэшами паролей	Нет

Поля в каждом элементе access[]:

Поле	Назначение	Генерируется
`username`	Логин пользователя	вручную
`cms_hash`	SHA-256 от `username:password` — JS-аутентификация в браузере	`add_user.sh`
`password_hash`	SHA-512 htpasswd-совместимый хэш — генерируется для совместимости, текущей аутентификацией не используется	`add_user.sh`

Не редактировать access[] вручную — всегда через tools/add_user.sh, который генерирует оба хэша атомарно.

Единая логика видимости:

`public`	`access`	Главная	Доступ
`true`	любой	виден всем	открыт без пароля
`false`	не пуст	не виден	по паролю из `access`
`false`	пуст / отсутствует	не виден	открыт (дефолт)

Файл `_category_.json`

{
  "label": "Название раздела",
  "position": 1
}

Обязателен в каждой из четырёх папок проекта. Без него раздел не отображается в index.md.

Картинки и медиафайлы

Правило — однозначно

Источник правды для всех медиафайлов — папка assets/ внутри папки проекта.

docs/
  vitiana-api-platform/
    assets/
      architecture.jpg    ← файл лежит здесь

Скрипт sync_assets.sh синхронизирует assets/ → static/<slug>/ перед каждой сборкой. Папка static/<slug>/ — производная, не редактировать вручную.

Синтаксис вставки

![Описание](/vitiana-api-platform/architecture.jpg)

Путь начинается с / — абсолютный от корня сайта. Тег <img> не использовать — создаёт проблемы компиляции MDX.

Загрузка через CMS-редактор

CMS при загрузке кладёт файл в docs/_uploads/ (временная папка, в .gitignore). После загрузки — переместить файл вручную в docs/<slug>/assets/ через файловый менеджер или git, затем вставить правильную ссылку.

mv docs/_uploads/myimage.jpg docs/vitiana-api-platform/assets/
git add docs/vitiana-api-platform/assets/myimage.jpg

Генерация `index.md` проекта

tools/build_project_index.sh <project-slug>

Читает структуру папки и собирает index.md автоматически. Файл перезаписывается полностью — не редактировать вручную.

Что читает:

_project_.json → label, description
Вложенные папки с _category_.json → список разделов в порядке position
assets/ → таблица медиафайлов (если не пуста)

Черновики

---
title: "Название"
draft: true
---

Черновик виден в npm run start (dev), не попадает в npm run build (продакшн) и в экспорт.

Управление доступами

Концепция

Единственный источник правды — файлы в репозитории. Никакой ручной настройки на сервере.

cms-config.json          ←  глобальный admin
_project_.json           ←  читатели конкретного проекта
        ↓
tools/build_auth.sh      ←  генерирует src/auth/project-access.js (JS-аутентификация)

Роли

Роль	Кто	Доступ
`admin`	владелец системы	все проекты + CMS
`viewer`	читатель проекта	только указанные проекты
анонимный	все остальные	только `public: true` проекты

Добавление пользователя

tools/add_user.sh vitiana-api-platform ivan mypassword
# Добавить/обновить admin пароль:
tools/add_user.sh --admin newpassword

Скрипт записывает в _project_.json → access[] хэш: cms_hash (SHA-256 от username:password) для JS-аутентификации в браузере.

После добавления пользователя запустить build_auth.sh чтобы обновить JS-модуль:

tools/build_auth.sh      # обновляет src/auth/project-access.js
npm run build            # или deploy_site.sh — оба вызывают build_auth автоматически

JS-аутентификация (браузерная)

Защищённые проекты (с непустым access[]) закрыты JS-слоем — он работает поверх статики и не зависит от сервера.

Компоненты:

Файл	Назначение
`tools/build_auth.sh`	Генерирует `src/auth/project-access.js` из всех `_project_.json`
`src/auth/project-access.js`	GENERATED. ES-модуль с картой `{ slug → [{ username, cms_hash }] }`
`src/clientModules/authGuard.js`	Хук `onRouteUpdate` — проверяет токен при каждом переходе по SPA
`src/pages/login.tsx`	Страница `/login` — форма входа с SHA-256 верификацией

Как работает:

При переходе на страницу проекта authGuard.js скрывает тело страницы и проверяет localStorage['docs-auth:<slug>']
Если токен совпадает с cms_hash любого из access[] — страница показывается
Если нет — редирект на /login?project=<slug>&next=<url>
После успешного входа токен сохраняется в localStorage. Повторный вход в рамках того же проекта не требуется (до смены браузера или явного выхода)
Разные проекты — разные токены, независимо

Важно: src/auth/project-access.js — файл генерируемый. Не редактировать вручную. Всегда регенерировать через build_auth.sh.

prebuild в package.json гарантирует что build_auth.sh запускается автоматически перед каждой сборкой — не нужно помнить вручную.

Вход в CMS-редактор (`/admin`)

CMS-редактор защищён формой входа в static/admin/index.html. В файле зашит SHA-256 хэш от строки username:password.

Почему хэш прямо в HTML-файле — это нормально:

Форма входа — это защита от случайного открытия страницы, не криптографическая гарантия. Реальная защита локального режима — то, что decap-server слушает только localhost и недоступен снаружи. Без запущенного decap-server CMS не работает вообще — форма входа лишь UX-барьер.

Если кто-то уже имеет доступ к файлам репозитория — он видит все документы напрямую без CMS. Хэш в этом случае ничего не добавляет к угрозе.

Единственный риск: публичный git-репозиторий с известным логином. Тогда SHA-256 от username:password можно перебрать офлайн. Решение — cms-config.json в .gitignore при публичном git (логин хранится там), тогда хэш без логина практически неперебираем.

Смена логина или пароля для CMS:

Одна команда обновляет всё — cms-config.json и index.html — атомарно:

tools/add_user.sh --admin <новый-пароль>

Если нужно сменить также логин — сначала отредактировать cms-config.json вручную:

# 1. Изменить username в cms-config.json
#    "admin": { "username": "новый-логин", ... }

# 2. Сгенерировать новые хэши под новый логин+пароль
tools/add_user.sh --admin <пароль>

Скрипт читает текущий username из cms-config.json, поэтому шаг 1 обязателен перед шагом 2.

Проверить текущий логин:

python3 -c "import json; print(json.load(open('cms-config.json'))['admin']['username'])"

Главная страница и навигация

Главная / открыта без пароля — но показывает только public: true проекты. Прямая ссылка на защищённый проект запросит пароль. Это позволяет передать ссылку конкретному человеку — он войдёт по паролю, не видя остальных проектов.

SSH-ключи для деплоя

Все скрипты деплоя работают в BatchMode (без интерактивного ввода пароля). Требуется SSH-ключ.

Настройка один раз

# 1. Сгенерировать ключ если нет
ssh-keygen -t ed25519 -C "docs-deploy"

# 2. Скопировать публичный ключ на сервер
# В WSL нет GUI — ssh-copy-id не может запросить пароль интерактивно.
# Нужен sshpass:
sudo apt-get install -y sshpass
sshpass -p 'пароль' ssh-copy-id -o StrictHostKeyChecking=accept-new -p 22 user@your-server.com

# 3. Проверить
ssh -p 22 user@your-server.com "echo ok"

Проверка перед деплоем

ssh -o BatchMode=yes -p 22 user@your-server.com "echo ok"
# Должно вывести: ok
# Если запрашивает пароль — ключ не настроен

Деплой: Shared хостинг (Apache)

Защита проектов реализована на JS-уровне — серверные файлы доступа не используются.

Ограничение: CMS-редактор (/admin) на shared недоступен — требует Node.js. Редактирование только локально.

Первый деплой (один раз)

# 1. Заполнить cms-config.json: site.url, shared.deploy_path, shared.ssh_host
# 2. Настроить SSH-ключ (см. раздел SSH-ключи)
# 3. Проверить соединение:
ssh -o BatchMode=yes -p 22 username@shared.yourdomain.com "echo ok"

Полный деплой одной командой

tools/deploy_site.sh --mode=shared

Выполняет по шагам:

sync_assets.sh — синхронизация медиафайлов
build_index.sh — обновление главной страницы
npm run build — сборка (включая build_auth.sh → доступы в бандл)
rsync build/ → shared.deploy_path по SSH

Деплой: VPS (nginx)

Поддерживаются два метода деплоя на VPS — задаётся в cms-config.json → vps.deploy_method:

Метод	Описание
`docker`	nginx в Docker-контейнере, маршрутизация через Traefik. Node.js на сервере не нужен. Рекомендуется.
`pm2`	Node.js + pm2 + nginx на сервере.

Полное руководство по настройке, конфигурации и добавлению домена: Деплой на VPS — Docker + Traefik

Деплой одной командой

# Метод из cms-config.json
tools/deploy_site.sh --mode=vps

# Явно указать метод
tools/deploy_site.sh --mode=vps --method=docker
tools/deploy_site.sh --mode=vps --method=pm2

Или через панель управления: tools.html → раздел «Публикация» → VPS · docker / VPS · pm2.

CMS на сервере (опционально)

По умолчанию CMS (/admin) работает только локально через npx decap-server. На сервере это не запускается.

Если нужна CMS на сервере — потребуется сменить backend в static/admin/config.yml:

# Вариант: git-gateway через Netlify Identity (для Netlify деплоя)
backend:
  name: git-gateway
  branch: main

# Вариант: gitea или Forgejo на своём сервере
backend:
  name: gitea
  repo: owner/repo
  app_id: <app_id>
  branch: main

Это требует отдельной настройки git-сервера и выходит за рамки базовой конфигурации. До реализации — CMS только локально.

Скрипты автоматизации

Все скрипты в tools/. Запускаются из любого места — путь к репозиторию определяется автоматически через git rev-parse --show-toplevel.

Зависимости: bash, python3, git. Для деплоя: rsync, scp, ssh, openssl.

`build_index.sh`

tools/build_index.sh

Генерирует docs/index.md — главную страницу со списком публичных проектов.

Читает: все docs/*/\_project_.json где public: true. Пишет: docs/index.md. Порядок: поле position, при равенстве — алфавит по slug. Когда: перед каждой сборкой; после добавления проекта или смены public/position.

`build_project_index.sh`

tools/build_project_index.sh <project-slug>

Генерирует docs/<slug>/index.md — страницу входа в проект.

Читает: _project_.json (label, description), _category_.json всех подпапок (разделы в порядке position), assets/ (список медиафайлов). Пишет: docs/<slug>/index.md — полностью перезаписывает, не редактировать вручную. Когда: при создании проекта, изменении структуры разделов или добавлении assets.

`sync_assets.sh`

tools/sync_assets.sh              # все проекты
tools/sync_assets.sh <slug>       # один проект

Синхронизирует docs/<slug>/assets/ → static/<slug>/ через rsync.

Пропускает папки где только .gitkeep. Важно: static/<slug>/ — производная папка, источник правды — assets/. Когда: перед сборкой если добавлялись медиафайлы; автоматически вызывается из deploy_site.sh.

`add_user.sh`

tools/add_user.sh <project-slug> <username> <password>   # добавить читателя
tools/add_user.sh --admin <password>                      # обновить пароль admin

Режим проекта: генерирует два хэша и записывает в access[] в _project_.json:

cms_hash — SHA-256 от username:password для JS-аутентификации в браузере
password_hash — SHA-512 htpasswd-совместимый хэш (генерируется для совместимости, текущей аутентификацией не используется)

Если пользователь уже существует — оба хэша обновляются.

Режим --admin: генерирует SHA-512 хэш → cms-config.json; генерирует SHA-256 хэш username:password для CMS-формы → static/admin/index.html. Оба файла обновляются атомарно.

Зависимости: openssl, python3. Пароль в открытом виде нигде не сохраняется.

После изменения пользователей проекта — запустить build_auth.sh для обновления JS-модуля.

`build_auth.sh`

tools/build_auth.sh

Генерирует src/auth/project-access.js — ES-модуль с таблицей доступов для JS-аутентификации в браузере.

Читает: поле cms_hash из access[] всех docs/*/\_project_.json.
Пишет: src/auth/project-access.js — полностью перезаписывает, не редактировать вручную.
Когда: автоматически через npm run prebuild перед каждой сборкой; вручную после добавления/изменения пользователей.

`deploy_access.sh`

tools/deploy_access.sh --mode=shared|vps

Stub-скрипт, сохранён для совместимости с deploy_site.sh. Ничего не генерирует — выводит пояснение что аутентификация встроена в JS-бандл через build_auth.sh.

`deploy_push.sh`

tools/deploy_push.sh --mode=shared|vps

Stub-скрипт, сохранён для совместимости с deploy_site.sh. Ничего не заливает — выводит пояснение что аутентификация встроена в JS-бандл через build_auth.sh.

`deploy_site.sh`

tools/deploy_site.sh --mode=shared
tools/deploy_site.sh --mode=vps

Полный деплой одной командой: sync_assets → build_index → npm run build (включает prebuild: build_auth.sh) → SSH-проверка → rsync build → (pm2 restart).

Читает из cms-config.json:

Режим	Поля
shared	`shared.ssh_host`, `shared.ssh_port`, `shared.deploy_path`
vps	`vps.ssh_host`, `vps.ssh_port`, `vps.remote_path`, `vps.pm2_app`, `vps.domain`

`export_project.sh`

tools/export_project.sh <project-slug>
# → exports/<slug>-YYYY-MM-DD.tar.gz

Архив одного проекта без данных доступа: копирует во временную папку → удаляет поле access из _project_.json → удаляет .gitkeep → упаковывает. Папка exports/ в .gitignore.

`export_public.sh`

tools/export_public.sh

Экспортирует все проекты с public: true. Вызывает export_project.sh для каждого.

`bundle_for_review.sh`

tools/bundle_for_review.sh <project-slug>
tools/bundle_for_review.sh --all
tools/bundle_for_review.sh <project-slug> --no-index

Собирает все MD-документы проекта в один последовательный файл и упаковывает в .tar.gz. Предназначен для передачи документации целиком в AI-агент с большим контекстным окном.

Порядок разделов: overview → reference → operations → development → остальное. Внутри каждого раздела — сначала index.md, затем остальные файлы по алфавиту.

Формат вывода: между документами вставляется разделитель . В конце — статистика (количество файлов, слов, символов).

Параметры:

<slug> — обрабатывает один проект
--all — обрабатывает все проекты по отдельности
--no-index — пропускает index.md файлы разделов (корневой index.md проекта пропускается всегда)

Результат: exports/<slug>-review-YYYY-MM-DD.tar.gz

`import_bundle.sh`

tools/import_bundle.sh <path> [--id bundle-YYYY-MM-DD-vNN] [--operator name]

Импортирует входящие документы в изолированную ветку import/<id>. Поддерживает три формата доставки:

Формат	Поведение
`.bundle`	git-bundle: верифицирует, fetches, создаёт ветку из FETCH_HEAD
`.tar.gz` / `.zip` с `.git` внутри	Извлекает архив, fetches из embedded репозитория
`.tar.gz` / `.zip` без `.git`	Создаёт ветку от `main`, rsync содержимого, коммит

Аргументы:

--id bundle-YYYY-MM-DD-vNN — явный ID импорта (по умолчанию генерируется автоматически по дате + счётчику)
--operator name — имя оператора в лог (по умолчанию operator, можно задать через OPERATOR= env)

Защиты:

.ops/locks/import.lock — параллельный импорт невозможен
Проверяет что ветка import/<id> ещё не существует

Лог: создаётся .ops/import-log/<id>.md с датой, оператором, source commit и статусом.

После импорта:

git diff main..import/<id> --stat   # посмотреть что изменилось
git merge import/<id>               # принять изменения

`serve_preview.sh`

tools/serve_preview.sh [port]   # по умолчанию 3001

Продакшн-сборка + локальный веб-сервер. Черновики не видны — как на деплое. Отличие от npm run start: нет hot reload, полная сборка.

Запрещено

Структура:

Хранить картинки в static/ напрямую — только через assets/ проекта
Создавать ветки под проекты — проекты различаются папками, не ветками
Держать актуальную версию документов вне Git
Папки в docs/ без _project_.json — невидимы для системы

Конфигурация:

Менять url и title в docusaurus.config.ts вручную — только через cms-config.json
Менять media_folder в config.yml — картинки через assets/ по стандарту

Безопасность:

Хранить пароли в открытом виде — только хэши через tools/add_user.sh
Включать cms-config.json (с хэшами паролей) в экспортный архив
Включать поле access из _project_.json в экспортный архив
Пушить в публичный git без добавления cms-config.json в .gitignore

Редактирование:

Редактировать index.md проекта вручную — перезапишется build_project_index.sh
Редактировать src/auth/project-access.js вручную — перезапишется build_auth.sh
Редактировать поле access[] в _project_.json вручную — только через add_user.sh (иначе cms_hash и password_hash рассинхронизируются)

Платформы

В системе работают две платформы документирования. Обе используют одну структуру папок и Git-репозиторий.

	Docusaurus + Decap CMS	TinaDocs + TinaCMS
Редактор	Markdown тулбар	Визуальный WYSIWYG
Формат файлов	`.md`	`.mdx`
Деплой	Статический HTML, Node.js не нужен на хостинге	Node.js обязателен
Руководство	`reference/Docusaurus - Decap CMS - Руководство по установке.md`	`reference/TinaDocs - Руководство по установке.md`

Версии компонентов

Зафиксированные версии на момент последней проверки (апрель 2026). При обновлении — менять здесь и в соответствующих файлах.

Компонент	Версия	Где используется	Как обновить
`decap-cms`	^3.0.0	`static/admin/index.html` — CDN ссылка	Использовать плавающую версию `^3.0.0`
`decap-server`	3.7.0	`package.json` — локальный прокси-сервер	`npm update decap-server`

Политика версионирования

decap-cms в CDN (static/admin/index.html) — использовать плавающую версию ^3.0.0:

s.src = 'https://unpkg.com/decap-cms@^3.0.0/dist/decap-cms.js';

Не фиксировать точную версию (например @3.12.2) — отдельные минорные релизы содержат регрессии (сломанный тулбар редактора и др.).

decap-server в package.json — зафиксирован через ^3.7.0 (патч-обновления автоматически, мажор — вручную).

Проверка актуальной версии

# Последняя версия decap-cms на npm
npm view decap-cms version

# Последняя версия decap-server
npm view decap-server version

# GitHub releases (последний тег)
# https://github.com/decaporg/decap-cms/releases

При обновлении decap-cms

Проверить CHANGELOG — нет ли ломающих изменений

Обновить версию в static/admin/index.html:

s.src = 'https://unpkg.com/decap-cms@X.Y.Z/dist/decap-cms.js';

Проверить локально: npx decap-server + открыть /admin
Обновить версию в этом документе

⚠ СИСТЕМА ПРЕДНАЗНАЧЕНА ДЛЯ ЛОКАЛЬНОГО ИСПОЛЬЗОВАНИЯ​

Настройка Git-репозитория​

Настройка cms-config.json​

Настройка docusaurus.config.ts​

Концепция: единый поток​

Потоки работы​

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

2. Хранение​

3. Локальный просмотр​

4. Деплой на сервер​

5. Экспорт​

Стандарт структуры папок​

Эталон​

Правила именования​

Правила определения названий​

Файл _project_.json​

Файл _category_.json​

Картинки и медиафайлы​

Правило — однозначно​

Синтаксис вставки​

Загрузка через CMS-редактор​

Генерация index.md проекта​

Черновики​

Управление доступами​

Концепция​

Роли​

Добавление пользователя​

JS-аутентификация (браузерная)​

Вход в CMS-редактор (/admin)​

Главная страница и навигация​

SSH-ключи для деплоя​

Настройка один раз​

Проверка перед деплоем​

Деплой: Shared хостинг (Apache)​

Первый деплой (один раз)​

Полный деплой одной командой​

Деплой: VPS (nginx)​

Деплой одной командой​

CMS на сервере (опционально)​

Скрипты автоматизации​

build_index.sh​

build_project_index.sh​

sync_assets.sh​

add_user.sh​

build_auth.sh​

deploy_access.sh​

deploy_push.sh​

deploy_site.sh​

export_project.sh​

export_public.sh​

bundle_for_review.sh​

import_bundle.sh​

serve_preview.sh​

Запрещено​

Платформы​

Версии компонентов​

Политика версионирования​

Проверка актуальной версии​

При обновлении decap-cms​