diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..01418a2 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,87 @@ +# AGENTS.md — правила работы с проектом dedinit.ru + +## Общие принципы + +1. Взаимодействие и документация — на русском языке. +2. Все важные решения и изменения фиксируются в README.md (кратко) и соответствующих документах в `docs/`. +3. Перед применением изменений проверяется корректность принятых решений. +4. Цель — максимально быстро публиковать контент без поломки сайта. + +## Структура документации + +- `README.md` — ТОЛЬКО краткое введение в проект для репозитория: + что это, стек, быстрый старт (сборка/деплой) и указатели на `docs/`. + Никакой подробной документации и истории изменений в README не держим. +- `docs/` — вся подробная документация проекта: + инструкции, справочники, дорожные карты, заметки об опыте настройки. +- `AGENTS.md` — правила работы для агентов (этот файл). +- Подробная эксплуатационная документация НЕ должна лежать в корне репозитория. + Новые документы создавать только в `docs/`. + +## Технологический стек + +| Параметр | Значение | +|----------|----------| +| Генератор | Hugo Extended 0.165.x | +| Тема | rDedInit (форк PaperMod) | +| Язык | Русский (ru-ru), timeZone Europe/Moscow | +| Формат статей | Bundle: `content/posts//index.md` (+ hero.svg и др.) | +| Git-хостинг | gitverse.ru — источник истины (kpa39l/dedinit.ru) | +| Деплой | SFTP на kpa39l.myjino.ru:2222 | + +## Статьи (контент) + +- Новые статьи: `content/posts//index.md`. +- Frontmatter: `date`, `lastmod` — в прошлом (Hugo молча не публикует + страницы с датой в будущем), `draft: false`, `title`, `slug`. +- hero.svg для статьи: `viewBox="0 0 1200 400"`, фон `#0a0c10`, + паттерн-гексагон `#1a2332`, заголовок моноширинный `#58a6ff`. + Копировать hero.svg из последнего поста как базу — единый стиль. +- Блочный код с подсветкой — обязателен там, где нужен (цель проекта). + +## Сборка и деплой + +```bash +# ЕДИНСТВЕННЫЙ способ деплоя — make deploy. Не заменять на rsync/ssh-exec: +# аккаунт Jino SFTP-only (exec request failed on channel 0). +export SSHPASS='<пароль SFTP>' +make deploy # hugo --minify + mirror public/ → /dedinit.ru +make deploy-dry-run # симуляция деплоя +make build # только сборка +make help # все команды +``` + +- `public/`, `.venv/`, `.hermes/` — в git не попадают (.gitignore). +- Пароль SFTP в открытом виде в репозиторий НЕ коммитить + (winscp_script.txt с паролем был вынесен из корня — см. `tools/`). + +## Git + +- Ветка `main`, источник истины — gitverse.ru, пуши через SSH + (`git@gitverse.ru:kpa39l/dedinit.ru.git`). +- Gitea (bigbox) — pull-mirror, туда отдельно не пушить. +- Коммиты — короткие, по смыслу изменений. +- Секреты и пароли в коммиты не добавлять. + +## Процессы и планирование + +- Планирование изменений — OpenSpec: `openspec/` (specs + changes). + Правки контента/кода — через openspec-скиллы из `.hermes/skills/` + (propose → design → apply → archive). +- Проверочные действия перед этапами: `hugo version`, `make build`, + контроль `hugo.toml`, `make deploy-dry-run`. + +## Обязательные проверки перед публикацией статьи + +1. `date` НЕ в будущем (иначе Hugo молча не публикует, без предупреждения). +2. `make build` проходит без ошибок. +3. Статья есть в сборке: `ls public/<год>//index.html`, + `grep -o '[^<]*'`, `grep -o 'hero.svg'`. +4. `git push origin main`, затем при необходимости `make deploy`. + +## Правила пользователя + +- Краткие статус-отчёты на русском языке. +- Тихие watchdog'и: уведомлять только при реальной проблеме. +- НЕ удалять и не перезаписывать данные пользователя без явного подтверждения. +- Перед действиями — читать доки проекта (STATUS/PRD/WALKTHROUGH/TODO.md, openspec) и прошлые сессии. \ No newline at end of file diff --git a/Makefile b/Makefile index 2e2ac69..7b38afb 100644 --- a/Makefile +++ b/Makefile @@ -13,7 +13,7 @@ else # Венв .venv создаётся автоматически таргетом venv (нужен paramiko). DEPLOY_CMD = .venv/bin/python tools/deploy_sftp.py DRYRUN_CMD = .venv/bin/python tools/deploy_sftp.py --dry-run - # Пароль берётся из переменной окружения SSHPASS (см. README.md / DEPLOY_INSTRUCTIONS.md) + # Пароль берётся из переменной окружения SSHPASS (см. README.md / docs/DEPLOY_INSTRUCTIONS.md) endif .PHONY: build deploy deploy-dry-run clean rebuild help venv @@ -27,7 +27,7 @@ deploy: build venv ifeq ($(PLATFORM),Windows) $(DEPLOY_CMD) else - @test -n "$$SSHPASS" || (echo "ОШИБКА: переменная SSHPASS (пароль SFTP) не задана. См. README.md / DEPLOY_INSTRUCTIONS.md"; exit 1) + @test -n "$$SSHPASS" || (echo "ОШИБКА: переменная SSHPASS (пароль SFTP) не задана. См. README.md / docs/DEPLOY_INSTRUCTIONS.md"; exit 1) $(DEPLOY_CMD) endif @@ -36,7 +36,7 @@ ifeq ($(PLATFORM),Windows) @echo "Выполняем проверку соединения с сервером..." $(DRYRUN_CMD) else - @test -n "$$SSHPASS" || (echo "ОШИБКА: переменная SSHPASS (пароль SFTP) не задана. См. README.md / DEPLOY_INSTRUCTIONS.md"; exit 1) + @test -n "$$SSHPASS" || (echo "ОШИБКА: переменная SSHPASS (пароль SFTP) не задана. См. README.md / docs/DEPLOY_INSTRUCTIONS.md"; exit 1) $(DRYRUN_CMD) endif @@ -66,4 +66,4 @@ help: @echo " make help - показать это сообщение" @echo "" @echo "Деплой: export SSHPASS='<пароль SFTP>'; make deploy" - @echo "Пароль хранится в DEPLOY_INSTRUCTIONS.md (winscp_script.txt для Windows)." \ No newline at end of file + @echo "Пароль хранится в docs/DEPLOY_INSTRUCTIONS.md (winscp_script.txt для Windows)." \ No newline at end of file diff --git a/README.md b/README.md index f6f8fa3..00ffeb2 100644 --- a/README.md +++ b/README.md @@ -1,100 +1,55 @@ # dedinit.ru -## Описание проекта +**dedinit.ru** — блог на генераторе статических сайтов [Hugo](https://gohugo.io) +(extended) с кастомной темой **rDedInit** (форк [PaperMod](https://github.com/adityatelange/hugo-PaperMod)). +Платформа для публикации лонгридов с поддержкой блоков кода и подсветки +синтаксиса. -Этот проект представляет собой блог на основе генератора статических сайтов Hugo с темой PaperMod. Основная цель проекта - создать платформу для публикации лонгридов с поддержкой блоков кода и подсветки синтаксиса, чего не хватает в других сервисах (Telegraph, VK, Writefreely). +## Быстрый старт -## Технические детали - -- Генератор статических сайтов: Hugo (расширенная версия) -- Тема оформления: PaperMod () -- Хранение контента: GitVerse () через SSH -- Настройка: bundle хранение статей - -## Статус проекта - -Проект находится в стадии разработки. Выполненные задачи: - -- Установлена Hugo расширенная версия (0.155.1) -- Создан новый сайт dedinit.ru -- Установлена и настроена тема PaperMod -- Настроено bundle хранение статей -- Решена проблема совместимости Hugo и темы PaperMod -- Репозиторий подключён к GitVerse (gitverse.ru:kpa39l/dedinit.ru) -- **Создана собственная тема rDedInit** на базе PaperMod - -## История изменений - -### 30 августа 2026 года - -- Написана и опубликована статья «Как я перевёл aux-задачи Hermes на локальные модели» (пост `20260830 - local aux models hermes`, slug `local-aux-models-hermes-qwen3`) -- Исправлена сборка с современными версиями Hugo: добавлен `defaultContentLanguage = 'ru'` в hugo.toml (Hugo 0.123+ требует, чтобы defaultContentLanguage совпадал с одним из `[languages]`, иначе ошибка `config value "en" does not match any language definition`) -- Установлен локальный git identity в репозитории: Storozhenko Evgeny -- Подробный опыт настройки локальных aux-моделей Hermes задокументирован в [docs/local-aux-models.md](docs/local-aux-models.md) - -### 31 января 2026 года - -- Установлена Hugo расширенная версия 0.155.1 -- Создан новый сайт dedinit.ru -- Установлена тема PaperMod -- Настроено bundle хранение статей -- Создан пример статьи в формате bundle -- Настроена интеграция с Gitea сервером - -### 5 марта 2026 года - -- Миграция репозитория на GitVerse (gitverse.ru:kpa39l/dedinit.ru) - -### 1 февраля 2026 года - -- Разработано решение для деплоя сайта через SFTP -- Настроен Makefile для кроссплатформенного деплоя (Windows/Linux/macOS) -- Создан скрипт winscp_script.txt для подключения и синхронизации файлов -- Обновлены инструкции по деплою в DEPLOY_INSTRUCTIONS.md и README.md - -## Принятые технические решения - -1. **Выбор Hugo**: Выбран генератор статичных сайтов Hugo для быстродействия и гибкости -2. **Расширенная версия Hugo**: Используется расширенная версия для поддержки SCSS -3. **Тема PaperMod**: Легкая и адаптивная тема с поддержкой темной/светлой темы -4. **Bundle хранение статей**: Используется формат bundle (папка с index.md) для удобного хранения статьи и связанных файлов -5. **Хранение на GitVerse**: Контент хранится на GitVerse для полного контроля -6. **SSH подключение**: Используется SSH для безопасного доступа к репозиторию -7. **Структура проекта**: Правильная иерархия папок с .gitignore для исключения ненужных файлов - -## Запуск проекта - -Для генерации сайта и просмотра его в браузере используйте следующие команды: - -- `hugo` - генерирует статический сайт в папку `public` -- `hugo server` - запускает локальный сервер для предварительного просмотра сайта в браузере (обычно доступен по адресу ) - -## Деплой сайта - -> **ЕДИНСТВЕННЫЙ способ деплоя сайта — `make deploy`.** Не деплойте вручную -> (rsync/ssh-exec напрямую не работают: аккаунт Jino SFTP-only). - -Специальные файлы: - -- `Makefile` — команды сборки и публикации (Unix: SFTP через `tools/deploy_sftp.py` - на paramiko; Windows: WinSCP.com) -- `tools/deploy_sftp.py` — рекурсивный mirror `public/` → `/dedinit.ru` - (с удалением лишнего, как `rsync --delete`), пароль из env `SSHPASS` -- `winscp_script.txt` — скрипт для WinSCP (Windows) -- `DEPLOY_INSTRUCTIONS.md` — инструкция по деплою - -Для публикации сайта на хостинге: - -```shell -export SSHPASS='<пароль SFTP из DEPLOY_INSTRUCTIONS.md>' -make deploy +```bash +hugo # сборка в public/ +hugo server # локальный сервер: http://localhost:1313 +make build # сборка через Makefile (hugo --minify) +make deploy # сборка + деплой (требует SSHPASS) ``` -Первая сборка создаст `.venv/` (paramiko). Для получения полного списка команд: +**ЕДИНСТВЕННЫЙ способ деплоя — `make deploy`.** Не заменять на rsync/ssh-exec: +аккаунт хостинга SFTP-only. Подробности — в `docs/DEPLOY_INSTRUCTIONS.md`. -```shell -make help +## Структура + +``` +dedinit.ru/ +├── content/posts/ # Статьи блога (bundle: папка с index.md + hero.svg) +├── themes/rDedInit/ # Кастомная тема на базе PaperMod +├── static/ # Статические ресурсы (favicon и т.д.) +├── docs/ # ВСЯ документация проекта +├── tools/ # Скрипты деплоя (deploy_sftp.py, winscp_script.txt) +├── hugo.toml # Конфигурация Hugo +├── Makefile # Сборка и деплой +├── README.md # Краткое введение (этот файл) +└── AGENTS.md # Правила работы для агентов ``` -Процесс кроссплатформенный: на Unix — SFTP (paramiko), на Windows — WinSCP.com. -НЕ удаляйте `make deploy` и не заменяйте его на прямой rsync. +## Документация + +Вся подробная документация — в каталоге [`docs/`](docs/): + +| Документ | О чём | +|----------|-------| +| [DEPLOY_INSTRUCTIONS.md](docs/DEPLOY_INSTRUCTIONS.md) | Деплой через SFTP (kpa39l.myjino.ru:2222) | +| [ROADMAP.md](docs/ROADMAP.md) | Дорожная карта проекта | +| [PAPERMOD_PARAMS.md](docs/PAPERMOD_PARAMS.md) | Справочник параметров темы rDedInit | +| [QWEN.md](docs/QWEN.md) | Настройки взаимодействия и описание проекта | +| [gitea-setup.md](docs/gitea-setup.md) | Интеграция с Gitea | +| [Telegram_frontend.md](docs/Telegram_frontend.md) | Оформление Telegram-постов | +| [favicon-logo-setup.md](docs/favicon-logo-setup.md) | Настройка favicon и логотипа | +| [local-aux-models.md](docs/local-aux-models.md) | Опыт: локальные aux-модели Hermes | +| [archive/](docs/archive/) | Архив устаревших документов | + +## Конвенции + +- Ветка `main`; источник истины — [gitverse.ru](https://gitverse.ru) (`kpa39l/dedinit.ru`), Gitea — pull-mirror. +- Правила работы для агентов — [`AGENTS.md`](AGENTS.md). +- Планирование изменений — OpenSpec (`openspec/`). \ No newline at end of file diff --git a/DEPLOY_INSTRUCTIONS.md b/docs/DEPLOY_INSTRUCTIONS.md similarity index 100% rename from DEPLOY_INSTRUCTIONS.md rename to docs/DEPLOY_INSTRUCTIONS.md diff --git a/PAPERMOD_PARAMS.md b/docs/PAPERMOD_PARAMS.md similarity index 100% rename from PAPERMOD_PARAMS.md rename to docs/PAPERMOD_PARAMS.md diff --git a/QWEN.md b/docs/QWEN.md similarity index 94% rename from QWEN.md rename to docs/QWEN.md index 0fee33b..2154fd1 100644 --- a/QWEN.md +++ b/docs/QWEN.md @@ -172,13 +172,13 @@ metaDataFormat = "yaml" | Файл | Описание | |------|----------| -| README.md | Основное описание проекта | -| ROADMAP.md | Дорожная карта развития | -| PAPERMOD_PARAMS.md | Справочник параметров темы | -| DEPLOY_INSTRUCTIONS.md | Инструкция по деплою | -| gitea-setup.md | Настройка интеграции с Gitea | +| README.md | Основное описание проекта (кратко) | +| docs/ROADMAP.md | Дорожная карта развития | +| docs/PAPERMOD_PARAMS.md | Справочник параметров темы | +| docs/DEPLOY_INSTRUCTIONS.md | Инструкция по деплою | +| docs/gitea-setup.md | Настройка интеграции с Gitea | | docs/favicon-logo-setup.md | Настройка favicon и логотипа | -| Telegram_frontend.md | Оформление Telegram-постов | +| docs/Telegram_frontend.md | Оформление Telegram-постов | --- diff --git a/ROADMAP.md b/docs/ROADMAP.md similarity index 100% rename from ROADMAP.md rename to docs/ROADMAP.md diff --git a/Telegram_frontend.md b/docs/Telegram_frontend.md similarity index 100% rename from Telegram_frontend.md rename to docs/Telegram_frontend.md diff --git a/.qwen/PROJECT_SUMMARY.md b/docs/archive/PROJECT_SUMMARY.md similarity index 100% rename from .qwen/PROJECT_SUMMARY.md rename to docs/archive/PROJECT_SUMMARY.md diff --git a/gitea-setup.md b/docs/gitea-setup.md similarity index 100% rename from gitea-setup.md rename to docs/gitea-setup.md diff --git a/ssh_setup_instructions.md b/docs/ssh_setup_instructions.md similarity index 100% rename from ssh_setup_instructions.md rename to docs/ssh_setup_instructions.md diff --git a/tools/deploy_sftp.py b/tools/deploy_sftp.py index b7679ff..e3462d2 100644 --- a/tools/deploy_sftp.py +++ b/tools/deploy_sftp.py @@ -4,7 +4,7 @@ Используется командой `make deploy` (единственный способ деплоя сайта). Jino-аккаунт kpa39l_dedinit — SFTP-only: удалённый exec (rsync/ssh) запрещён, поэтому заливаем через SFTP с рекурсивным mirror и --delete (как rsync). -Пароль — из env SSHPASS (см. README.md / DEPLOY_INSTRUCTIONS.md). +Пароль — из env SSHPASS (см. README.md / docs/DEPLOY_INSTRUCTIONS.md). """ import os import stat as stmod @@ -25,7 +25,7 @@ REMOTE = os.environ.get("DEDINIT_REMOTE", "/dedinit.ru") DRYRUN = "--dry-run" in sys.argv if not PASS: - print("ОШИБКА: переменная SSHPASS (пароль SFTP) не задана. См. README.md / DEPLOY_INSTRUCTIONS.md", file=sys.stderr) + print("ОШИБКА: переменная SSHPASS (пароль SFTP) не задана. См. README.md / docs/DEPLOY_INSTRUCTIONS.md", file=sys.stderr) sys.exit(1) LOCAL = os.path.abspath(LOCAL) diff --git a/winscp_script.txt b/tools/winscp_script.txt similarity index 100% rename from winscp_script.txt rename to tools/winscp_script.txt