Quartz 4

Authoring

2 min readBohdan Derkach

Правила та поради створення документації

Три важливі правила

  1. Краще поступово, але регулярно, по фічі. Будь-яку яку фічі або її оновлення треба пушити одразу, не тримати локально тижнями.
  2. docs — публікаційна гілка. Пишем фічі і доку до них на будь-якій гілці → мердж у docs → пуш. Сайт збирається з docs кожного сервісу.
  3. Робиш оновлення в прод — відпишись про доку. Один рядок: «оновив docs/X» або «доки на це нема».

Поради для генерації через AI

Ітеративно, по одній сторінці за раз — не 20 файлів одним заходом.

  1. Розробник стисло описує суть фічі та всі її нюанси. Акцентує увагу на важливому та вказує в яких файлах чи методах це описано. Просить AI порівняти опис та реальну логіку, перевірити на помилки та доповнити і відформатувати опис згідно правил.
  2. AI все аналізує та ставить питання в разі необхідності уточнень; якщо все ясно — одразу пише.
  3. AI формулює за карткою типу з CONVENTIONS. Тільки сказане юзером, нічого «для повноти».
  4. Розробник рев’ює → правки → фіксація → наступна сторінка.

Шпаргалка команд

Підтягнути свіжі правила у сервісний репо

AI у сервісному репо читає правила з локальної копії .shared-docs/ — без sync вона застаріває.

# один раз — клонувати stack-docs сусідом:
git clone git@github.com:it-monkeys/stack-docs.git ../stack-docs
 
# щоразу коли треба свіжу копію:
git -C ../stack-docs pull
node ../stack-docs/scripts/sync-shared-docs.mjs

Скрипт копіює правила у .shared-docs/ поточного репо. Папка в .gitignore — не редагувати (перепише наступний sync), не комітити.

Коли запускати: AI діє за старою конвенцією · щойно мерджили нове правило · профілактично раз на тиждень.

Локальний прев’ю сайту без CI

Hot-reload прев’ю Quartz для ітерацій над стилями/розкладкою — зміни видно за секунди, без черги CI.

Один раз:

  1. Node ≥22 через fnm: winget install Schniz.fnm, у новому Git Bash — echo 'eval "$(fnm env --use-on-cd --shell bash)"' >> ~/.bashrc && source ~/.bashrc && fnm install 22. У stack-docs/ лежить .node-version — версія перемкнеться сама при cd.
  2. Клонувати Quartz поряд: git clone https://github.com/jackyzha0/quartz.git ./quartz-local && cd quartz-local && npm ci (з кореня, де лежить stack-docs).

Щоразу:

cd stack-docs
node scripts/dev-preview.mjs     # → http://localhost:8080, Ctrl+C — стоп

Якщо щось не так: node -v показує стару версію → fnm use 22 (або перевір ~/.bashrc) · skipping <service> — not cloned locally → нормально, працює лише з клонованим · крос-сервісні wikilinks можуть 404-ити локально — на проді працюють.

Graph View

Backlinks