Quartz 4

README

4 min readBohdan Derkach

Stack Docs

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

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

Принципи

  1. Довідник, не туторіал. Знайти потрібне за 10 секунд, а не читати з початку.
  2. Чому, не як. Описуємо неочевидні рішення і нюанси. Синтаксис коду не дублюємо.
  3. UI — хребет, бек — опорні картки. Читач стартує з UI (що бачить), переходить на бек по лінках.
  4. API — це Swagger, не markdown. Контракт API живе в auto-Swagger сервісу. У docs тільки бізнес-нюанси і deeplinks.
  5. Один файл — одна одиниця. Розрізаємо на окремі сторінки, лінкуємо.
  6. Документація живе в коді сервісу. Кожен сервіс тримає свої доки в <repo>/docs/. Цей репо stack-docs — лише корінь і агрегатор.

Як це фізично влаштовано

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

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

push у будь-який сервіс  →  GitHub Actions stack-docs  →  Cloudflare Pages
       (docs/**)              (клонує всі сервіси,           (docs.besocial.tech)
                               збирає, білдить Quartz)
  • Тригер: push в docs/** будь-якого сервісного репо
  • Час до сайту: 1-2 хв
  • Дія від людини: жодної

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

В stack-docs/ коммітяться:

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

В stack-docs/ НЕ коммітиться:

  • services/* — там symlinks/snapshots сервісних доків. У .gitignore.

Це ключове. Не дублюємо контент сервісів у stack-docs git. Тому “пулити 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 як завжди разом з кодом
  3. Через 1-2 хв зміни на docs.besocial.tech

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

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

Один раз:

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

Далі: щоб бачити свіжі зміни — git pull у відповідному сервісному репо. В Obsidian оновиться автоматично через symlink.

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

Це йде у stack-docs.

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

Я хочу подивитись доку конкретного сервісу без локального налаштування

Просто відкрий docs.besocial.tech/services/<name> у браузері.

Доступи

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

Лінки між сервісами

КудиЯк писати
Всередині свого сервісу[[Назва файлу]] (звичайний wikilink)
На інший сервіс[[services/<service>/<шлях>/<файл>|людська назва]]
На глобальний контент[[glossary]], [[roles/director]], [[entities/Lady]]
На API endpointURL deeplink на Swagger: https://api.besocial.tech/<service>/api-docs/v2#/<Tag>/<Operation>

FAQ

Чи можу я редагувати доку без stack-docs локально? Так. Відкривай <service>/docs/ як vault напряму. Більшість розробників так і робитимуть.

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

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

Якщо я в режимі «один сервіс» і ставлю крос-сервіс лінк — він буде червоним, це баг? Ні, це нормально. У твоєму локальному vault цього файла нема. На зібраному сайті лінк працює.

Де писати API-контракт (запит/відповідь)? Не в markdown. У сервісі через routing-controllers декоратори → автоматичний Swagger. У doc-сторінці пишемо тільки бізнес-нюанси і deeplink на Swagger.

Graph View

Backlinks