Stack Docs

Це головний репозиторій документації проєкту. Він зберігає глобальні: правила та фічі. Все це збирається єдиний сайт docs.besocial.tech з документацій усіх сервісів.

Як це влаштовано

Три незалежних канали. Розуміти кожен окремо.

1. Як оновлюється сайт документаці

push у stack-docs (master)   ─┐
ручний workflow_dispatch     ─┤→  GitHub Actions stack-docs  →  Cloudflare Pages
cron 04:00 UTC щодоби        ─┘   (клонує всі сервіси)

Час від тригера до сайту: 1-2 хв.

2. Git stack-docs (тільки глобальне)

В цьому репо описуємо тільки глобальні артефакти:

README, CONVENTIONS, AUTHORING, glossary
architecture/ — мапа сервісів і їх взаємодії
entities/ — крос-сервісні сутності (User, Lady, Message …)
features/ — бізнес-фічі (Statistics, Sender, …)
scripts/, quartz-overrides/, .github/workflows/

НЕ коммітиться: services/* — там symlinks/snapshots сервісних доків (у .gitignore). Контент сервісних доків живе у їхніх репо.

3. Через Obsidian можна зручно редагувати документацію сервісу

Відкрити <service>/docs/ як vault.
Бачиш тільки свій сервіс.
Крос-сервісні wikilinks показуються сірими — на сайті працюють.

4. Локальний прев’ю Quartz без CI

Інструкція описана в AUTHORING

Як правильно оновити документацію?

На робочій гілці знаходиш <repo>/docs/, редагуєш md
Краще окремо комітити зміни і мьоржити це — у гілку docs

Я хочу додати глобальний термін / роль / ентіті / фічу

Це йде у stack-docs.

git pull в stack-docs
Редагуєш glossary.md / entities/<entity>.md / features/<feature>.md
git commit && git push
Сайт оновлюється

Я хочу подивитись доку конкретного сервісу

docs.besocial.tech/services/<name> у браузері. Без локального налаштування.

Доступи

Сайт — поки публічний. TODO: закрити по емейлах (через Cloudflare Access або інший gate).
CI stack-docs — має технічний токен з read-only до всіх сервісних репо. Один раз налаштовується.
Локально — sync пропускає репо до яких немає доступу. Не падає, не блокує.

Quartz 4

Explorer

README