Quartz 4

README

4 min readBohdan Derkach

Stack Docs

Корінь документації проєкту. Тут лежить глобальне (конвенції, глосарій, ролі, мапа сервісів, крос-сервісні сутності і фічі) і збирається єдиний сайт docs.besocial.tech з документацій усіх сервісів.

Цей файл — як ця документація фізично існує і як нею користуватись. Правила формату — у CONVENTIONS.md. Процес заповнення — у AUTHORING.md.

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

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

1. Сайт (читачі)

push у stack-docs (master)   ─┐
ручний workflow_dispatch     ─┤→  GitHub Actions stack-docs  →  Cloudflare Pages
cron 04:00 UTC щодоби        ─┘    (клонує всі сервіси,           (docs.besocial.tech)
                                   білдить Quartz)
  • Що тригерить білд зараз: push у master stack-docs, ручний запуск (Actions → Build & Deploy Docs → Run workflow), або cron о 04:00 UTC.
  • Сервісні пуші (push у гілку docs сервісного репо) поки не тригерять білд автоматично. Зміни підбирає cron наступного дня, або ручний запуск, або найближчий пуш у stack-docs. План перейти на repository_dispatch з кожного сервісу — закладений у workflow, але сервіси ще не пушать цю подію. TODO.
  • Час від тригера до сайту: 1-2 хв.

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

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

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

НЕ коммітиться: services/* — там symlinks/snapshots сервісних доків (у .gitignore). Контент сервісних доків живе у їхніх репо. Тому «зробити pull у stack-docs щоб побачити зміну в golden» — не існує.

3. Локальний Obsidian (для редакторів)

Два режими — обираєш один раз під себе.

«Один сервіс» (стандартно для більшості):

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

«Повний vault» (для частих перемикань або редагування глобального):

  1. git clone stack-docs поряд зі своїми сервісними репо
  2. node scripts/sync.mjs — створить symlinks services/<name> → ../<service-repo>/docs
  3. Відкрити stack-docs/ як vault
  4. Бачиш все що клонував локально як один vault з єдиним графом і пошуком
  5. Редагуєш будь-який файл — фізично змінюється файл у відповідному репо сервісу

Symlink-магія: коли колега пушить — ти робиш git pull у stack-<service> і Obsidian одразу бачить зміну. Без повторного sync.

Що з чим робити

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

Працюєш у своєму репо як завжди.

  1. Заходиш у <repo>/docs/, редагуєш md
  2. git commit && git push разом з кодом (стандартно — у гілку docs)
  3. Зміни на сайт потраплять наступним запуском workflow stack-docs — або cron’ом о 04:00 UTC, або ручним запуском (Actions → Build & Deploy Docs → Run workflow), або наступним push’ем у stack-docs

Не потрібно ні pull, ні sync, ні нічого від stack-docs.

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

Один раз:

  1. git clone stack-docs поряд з іншими сервісами
  2. cd stack-docs && node scripts/sync.mjs
  3. Відкрити stack-docs/ в Obsidian

Далі — git pull у відповідному сервісному репо. В Obsidian оновиться сам.

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

Це йде у stack-docs.

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

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

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

Доступи

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

FAQ

Чи можу я редагувати доку без stack-docs локально? Так. Дока кожного сервісу лежить у <repo>/docs/ свого репо і редагується незалежно. Текст може посилатись на глобальне через wikilinks ([[glossary]], [[entities/Lady]], [[roles]], [[features/statistics]]) — у локальному vault сервісу такі лінки будуть червоними, на зібраному сайті спрацюють.

Чи треба мені щось робити після того як колега запушив у golden? Для сайту — ні, оновиться при наступному запуску workflow. Для свого Obsidian (якщо в режимі повного vault) — git pull у stack-golden.

Що таке services/ і чому воно в gitignore? Папка куди sync-скрипт кладе symlinks на сервісні репо. Контент живе в їхніх репо. Дублювати не треба.

Graph View

Backlinks