Quartz 4

quartz-v5-migration

3 min readBohdan Derkach

quartz-v5-migration

Quartz v5 — план міграції

stack-docs/.github/workflows/docs.yml · quartz-overrides/ · scripts/dev-preview.mjs

Чому ми запінені на Quartz v4.5.2 і що треба, якщо колись переходити на v5. Загальний пайплайн доки — Docs Pipeline.

Поточний стан

CI пінить Quartz на тег v4.5.2 (git clone --branch v4.5.2). До цього clone тягнув HEAD upstream без піна — і коли автор Quartz випустив breaking v5.0.0, білд почав падати на рівному місці (не через зміни в доках). Пін зафіксував робочу версію.

Не знімати пін “щоб взяти свіже” — це поверне той самий breakage. Підняття версії — свідома окрема задача (цей файл).

Що зламало білд

У v5 quartz/components/Head.tsx робить:

import { CustomOgImagesEmitterName } from "../../.quartz/plugins"

Ядро Quartz тепер реферить user-space файл .quartz/plugins, якого в нашому setup нема. Наш пайплайн — clone ядро → rsync quartz-overrides поверх; в overrides лежить тільки ContentMeta.tsx + custom.scss, без .quartz/. У v4 його й не треба було. У v5 резолв падає → білд падає.

Що реально змінилось у v5

Головне — не у фіч-листі, а в архітектурі й setup:

v5v4 (наш)Наслідок для міграції
Плагіни — окремо-встановлювані модулі: npx quartz plugin install --from-configплагіни вбудовані в ядроядро реферить .quartz/plugins; CI має встановлювати плагіни, а не лише clone+rsync
quartz.config.yaml (YAML)quartz.config.ts (TypeScript)конфіг переписати з .ts на .yaml
Node v22 + npm 10.9.2 мінімумNode 20 вистачалоCI вже на Node 22, локально — .node-version теж 22, ОК
CLI npx quartz create / syncпростіший флоуновий онбординг-флоу

Фіч-лист v5 (search, graph, darkmode, OG, i18n, wikilinks, callouts, Canvas…) — майже все було і в v4. Реально нове/докручене: Bases (database-like views — tables/cards/galleries), encrypted pages, reader mode, stacked pages. (TODO звірити точний diff v4→v5 — офіційний changelog v5 на момент написання не віддавався.)

Що НЕ зламається

  • Контент (docs/*.md) — markdown стабільний. Заголовки, таблиці, wikilinks, frontmatter рендеряться так само. Існуючі сторінки переживуть.
  • Obsidian — не зачіпається взагалі. Obsidian і Quartz незалежні споживачі тих самих .md; версія Quartz на редагування у vault не впливає. Фічі-рендеру сайту (graph/search/OG/encryption) Obsidian не бачить.

Що ТРЕБА адаптувати (тут уся робота)

  1. .quartz/plugins — створити user-space plugins-конфіг і покласти у quartz-overrides/ (або перейти на офіційний флоу npx quartz plugin install --from-config).
  2. CI Setup Quartz — навчити встановлювати плагіни, не лише clone + rsync. Звірити з Docs Pipeline кроком 3-4.
  3. Конфіг — quartz.config.ts → quartz.config.yaml.
  4. Overrides — ContentMeta.tsx зав’язаний на внутрішнє API QuartzComponent. Якщо v5 змінив сигнатури — переписати. custom.scss (@use "./base.scss", data-slug скоупи) — звірити що base.scss на місці.
  5. Скрипти — inject-doc-meta.mjs, rewrite-service-wikilinks.mjs, dev-preview.mjs — перевірити що залежності на обробку frontmatter/слагів/wikilinks не змінились.

Коли взагалі переходити

Єдина вагома причина зараз — Bases (database-views): зручно для матриць доступу типу index. Решта фіч у нас уже є на v4.5.2. До того часу — лишаємось на піні.

Чеклист (коли дозріє рішення)

  • Підняти v5 локально через dev-preview.mjs, зібрати список того що падає
  • Створити .quartz/plugins під наш набір (mermaid, OG, search, i18n…)
  • Перевести quartz.config.ts → .yaml
  • Переписати ContentMeta.tsx під v5 component API (якщо змінилось)
  • Оновити CI Setup Quartz: plugin install --from-config після clone
  • Звірити inject-doc-meta / rewrite-service-wikilinks зі свіжим Quartz
  • Зняти пін v4.5.2 → закріпити новий тег v5.x.x
  • Прогнати повний білд + deploy на staging перед master

Graph View

Backlinks