Quartz 4

Docs-pipeline

6 min readBohdan Derkach

Docs-pipeline

Docs Pipeline

stack-docs/.github/workflows/docs.yml · scripts/inject-doc-meta.mjs · scripts/build-changelog.mjs · quartz-overrides/

Як stack-docs рендериться у єдиний сайт docs.besocial.tech. ~2-3 хв на тригер.

Як це працює

  1. Тригер — один з трьох:

    • push у master stack-docs зі змінами в **/*.md, scripts/, quartz-overrides/, workflow
    • repository_dispatch з типом service-docs-updated (його шлють сервісні репо коли в них змінюється docs/)
    • cron щодоби о 04:00 UTC — запасний механізм
    • workflow_dispatch (ручний запуск з UI Actions)

  2. Checkout stack-docs з повною git-історією (fetch-depth: 0).

  3. Setup Quartz — клонується свіжий Quartz у _quartz/.

  4. Apply overrides — rsync stack-docs/quartz-overrides/ _quartz/.

  5. Copy root content — все з кореня stack-docs (окрім services/, scripts/, .github/, quartz-overrides/, тощо) у _quartz/content/.

  6. Inject metadata for root — inject-doc-meta.mjs --repo stack-docs --src . додає у frontmatter modified і author з git log stack-docs.

  7. Aggregate services — для кожного запису в SERVICES env:

    • клонується сервісне репо з PAT (depth=200, потрібна свіжа гілка з docs/)
    • rsync <repo>/docs/ _quartz/content/services/<vault>/
    • rewrite-service-wikilinks.mjs — переписує relative wikilinks ([[ui/Chat]] → [[services/<vault>/ui/Chat]]) і basename-лінки які мають локальний match ([[Canvas]] → [[services/<vault>/Canvas]]). Без цього кроку сервісні wikilinks ламаються в спільному vault — Quartz shortest mode не вміє резолвити slash-форми.
    • inject-doc-meta.mjs --repo <repo> --src docs --target ... --prefix services/<vault>/
    • тимчасова папка чиститься

    .canvas файли копіюються в build, але Quartz їх нативно не рендерить — це обмеження. Для візуальних мап на сайті використовуємо mermaid у тілі md-сторінок (зокрема index.md сервісу). canvas-to-mermaid.mjs залишився в scripts/ як реалізована опція автоконвертації, зараз не використовується через слабкий auto-layout для великих канв.

  8. Build changelog — build-changelog.mjs збирає _changelog-partial.json з усіх піддиректорій у єдиний changelog.md.

  9. Build Quartz — npx quartz build → _quartz/public/.

  10. Deploy — wrangler pages deploy на Cloudflare Pages projект stack-docs.

Список сервісів

Редагується у env.SERVICES workflow-файла. Формат рядка:

<vault_name>:<repo_name>:<branch>
  • vault_name — як називається папка у vault (напр. electron, golden)
  • repo_name — назва репо в GitHub-org, не локальна папка. Зараз єдине розходження — локальна папка stack-electron, а на GitHub репо називається electron (історично). Тому в SERVICES electron:electron:refactor. Коли клонуєш сервіси для перевірки — git ls-remote https://github.com/it-monkeys/<repo_name> дасть точно.
  • branch — гілка з якої беремо docs/ (різниться між репо: десь master, десь refactor, десь update_swagger)

Якщо в репо ще нема docs/ — пайплайн пропускає його з warning’ом, не падає.

Як тригернути ручно

Поки webhook’и з сервісів не налаштовані, оновлення сайту після зміни доки в сервісі робиться одним з трьох способів:

1. GitHub UI (найшвидше).

  • github.com/it-monkeys/stack-docs/actions
  • Зліва обрати workflow Build & Deploy Docs
  • Над списком ранів буде блакитна смуга з текстом «This workflow has a workflow_dispatch event trigger.» — у її правій частині кнопка Run workflow ▼.
  • Клік → dropdown Use workflow from: Branch master → кнопка Run workflow.
  • Через ~1.5 хв білд завершиться, сайт оновиться.

2. gh CLI (якщо встановлено gh):

gh workflow run docs.yml --repo it-monkeys/stack-docs

3. Порожній коміт у stack-docs (без UI):

cd stack-docs
git commit --allow-empty -m "trigger rebuild" && git push

Тригерить workflow по push фільтру.

4. Cron щодоби о 04:00 UTC — нічого не робиш, ранкова зміна сама опиниться на сайті за добу.

Опційно: webhook з сервісного репо

Якщо хочеться щоб push у <service>/docs/ одразу тригерив білд stack-docs — кладемо .github/workflows/notify-stack-docs.yml у сервісне репо за шаблоном stack-docs/scripts/service-trigger-template.yml.

Передумови у сервісному репо:

  • secret STACK_DOCS_DISPATCH_TOKEN — fine-grained PAT з permission Actions: Read and write на it-monkeys/stack-docs (один токен на всі сервіси)
  • branch у paths workflow має збігатись з branch у SERVICES stack-docs

Має сенс налаштовувати коли 2+ людей паралельно редагують доки і набридло натискати Run workflow вручну.

Секрети у stack-docs

SecretПризначенняТермін дії
SERVICES_READ_TOKENFine-grained PAT з Contents: read на всі сервісні реподо 1 року (GitHub обмеження для PAT до org-репо)
CLOUDFLARE_API_TOKENAPI токен Cloudflare з permission на Pagesза вибором при створенні (типово без expiration)
CLOUDFLARE_ACCOUNT_IDID акаунту Cloudflareне протухає

Ротація SERVICES_READ_TOKEN

Токен живе максимум 1 рік (GitHub-обмеження для fine-grained PAT що дають доступ до org-репо). Коли протухне — workflow почне падати на кроці Clone services and aggregate docs з 401/404 на git clone.

GitHub за ~7 днів до експірації шле email-нагадування власнику токена. Краще перестворити заздалегідь.

Як перестворити

  1. GitHub → профіль → Settings → Developer settings → Personal access tokens → Fine-grained tokens
  2. Generate new token зі старими параметрами:
    • Token name: stack-docs-services-read
    • Resource owner: it-monkeys
    • Expiration: 1 year (максимум)
    • Repository access: Only select repositories — обрати всі сервісні репо (stack-electron, stack-golden, stack-client, stack, stack-prime, stack-udate, stack-chathouse, stack-academy, stack-ai)
    • Repository permissions → Contents: Read-only (Metadata: Read-only додасться автоматично як Required)
  3. Якщо org має policy на approval — попроси org-owner схвалити у it-monkeys → Settings → Personal access tokens → Pending requests.
  4. У it-monkeys/stack-docs → Settings → Secrets and variables → Actions → SERVICES_READ_TOKEN → Update value (вставити новий токен).
  5. Старий токен можна revoke у Fine-grained tokens після того як перевірив що новий працює.
  6. Перевірка: Actions → Build & Deploy Docs → Run workflow. Якщо проходить крок Clone services без warning’ів про 401 — все ок.

Важливо: не забувай оновлювати список репо у пункті 2 коли в проєкт додається новий сервіс — інакше workflow тихо буде skip’ати його з варнінгом «не вдалось клонити».

Метадані файлів

Інжектиться у frontmatter:

  • modified — ISO 8601 дата останнього коміту що торкався файла (з відповідного репо!)
  • author — %an останнього коміту
  • tags — JSON-array з першого рядка body (Obsidian inline-теги #x #y)

Файли в репо НЕ модифікуються — інжект на копії у _quartz/content/. Локально в Obsidian усе як було.

Нюанси

  • fetch-depth: 0 обов’язковий — без нього git log поверне 1 коміт і дати/changelog зламаються.
  • Сервісні репо клонуються --depth=200 — компроміс між швидкістю і точністю історії. Якщо потрібна повна історія — підвищити або прибрати.
  • concurrency: docs-build — два пайплайни одночасно не біжать. Запит що прийшов поки інший виконується — стає у чергу (cancel-in-progress: false).
  • Cron 04:00 UTC — підстраховка на випадок якщо webhook з сервісу загубився. Не критичний — головний канал це repository_dispatch.
  • _changelog-partial.json — тимчасові артефакти що залишають inject-doc-meta після кожного репо. build-changelog.mjs їх збирає і видаляє. На сайт не попадають.
  • Файли крос-сервісних wikilinks з префіксом services/<vault>/ — тому коли стійкий лінк ставиш на чужий сервіс у root-доці, пиши [[services/golden/api/index]].

Чек-ліст коли ламається пайплайн

  • Дата на сторінці = unix epoch (1970) → fetch-depth не 0 або сервіс склонувався без історії (підвищити depth)
  • Сервіс не з’явився на сайті → перевір що додано в env.SERVICES, що гілка існує, що PAT не протух
  • Webhook з сервісу не тригерить білд → перевір STACK_DOCS_DISPATCH_TOKEN в сервісному репо, дивись Actions runs у stack-docs
  • Cloudflare deploy впав → перевір CLOUDFLARE_API_TOKEN і CLOUDFLARE_ACCOUNT_ID
  • Quartz побудувався з помилкою про брокен лінк → лінк на файл який не існує у vault. Якщо це крос-сервіс — перевір що цільовий сервіс має docs/ і присутній у SERVICES.

Як змінити пайплайн

  • Додати сервіс — рядок у env.SERVICES. Якщо репо вже має docs/ — підхопиться при наступному запуску.
  • Прибрати сервіс — видалити рядок. Старий контент зникне з сайту після наступного білду.
  • Змінити вигляд автора/дати — quartz-overrides/quartz/components/ContentMeta.tsx.
  • Додати ще overrides Quartz-компонента — кладемо у quartz-overrides/quartz/components/<Name>.tsx. Rsync скопіює автоматично.
  • Розширити changelog — функції в build-changelog.mjs.

Зв’язки

  • Тригериться: пуш у stack-docs master, repository_dispatch з сервісів, cron, ручний dispatch
  • Читає: git log усіх сервісних репо
  • Пише: _quartz/content/** (тимчасово, у CI)
  • Деплоїть: docs.besocial.tech (Cloudflare Pages)

Graph View

Backlinks