Установка и настройка Quartz 4 в этом репозитории

Эта заметка не про абстрактную установку Quartz на Windows и не про Publication Center как главный способ публикации. Она про более практичный момент: как превратить папку с Markdown-страницами в живой сайт Smirnoff, не потеряв контроль над сборкой, preview и публикацией. В текущем репозитории уже есть структура контента, кастомные компоненты, CI, деплой на GitHub Pages и отдельная инфраструктура для локальной проверки.

Проще говоря, это инструкция не «как начать с нуля», а как уверенно работать именно с этим проектом: какие версии нужны, где лежит контент, какие команды запускать и почему эти команды важны перед публикацией наружу.

Что нужно для работы

Чтобы Quartz не превращался в набор «магических» команд, сначала стоит зафиксировать окружение. Проект рассчитан на современный Node.js:

Node.js >=22;
npm >=10.9.2;
Git;
любой редактор Markdown или Obsidian, если удобно писать заметки именно там.

Контент лежит прямо в content. Это важная деталь: источник сайта находится рядом с конфигурацией и кодом, а не во внешнем Windows-пути и не в отдельном обязательном vault. Obsidian можно открыть на этой папке и писать заметки привычным способом, но для сборки Quartz главным источником уже является сам каталог content в репозитории.

Структура проекта

Когда статья из заметки становится частью сайта, полезно понимать, где заканчивается текст и начинается инфраструктура. Основные места, с которыми приходится работать:

content — Markdown-страницы, статьи, проектные материалы, юридические документы;
quartz — компоненты, плагины, стили, клиентские inline-скрипты;
quartz.config.ts — общая конфигурация сайта, тема, плагины и emitters;
quartz.layout.ts — раскладка колонок, лендинговые исключения, подключение компонентов;
quartz/static/data — JSON-данные для главной, контактов, библиотеки и других data-driven блоков;
public — результат production-сборки;
docs — отдельный output для preview-документации;
tools/serve-public.ts — локальный сервер для уже собранного public с поддержкой clean URLs.

content/index.md, content/library.md и страница контактов в этом проекте не работают как обычные статьи один к одному. Для них в layout есть условия, которые подставляют специальные компоненты. Поэтому при правке таких страниц важно смотреть не только на Markdown, но и на то, как страница собирается в итоговом интерфейсе.

Команды из package.json

Актуальные команды такие:

npm run quartz
npm run docs
npm run site:dev
npm run site:preview
npm run check
npm run format
npm test

На практике чаще всего нужны три сценария: спокойно писать и смотреть результат локально, проверить уже собранный public и убедиться, что проект проходит автоматические проверки.

Разработка сайта

npm run site:dev

Скрипт запускает Quartz build с --serve --watch и output-директорией content. Это рабочий локальный режим: можно менять Markdown, смотреть, как страница выглядит в браузере, и сразу ловить проблемы с clean-URL поведением Quartz, а не после деплоя.

Preview уже собранного public

npm run site:preview

Этот скрипт запускает tsx tools/serve-public.ts. Он отдаёт public и аккуратно обрабатывает extensionless routes: например, /Кoнтакты должен открываться как Quartz-страница, а не падать из-за отсутствия физической папки. Такой preview полезен перед публикацией, когда нужно проверить именно готовую статику, а не режим разработки.

Можно передать директорию и порт напрямую:

tsx tools/serve-public.ts public 4173

Проверки

npm run check
npm test

npm run check делает typecheck и prettier check. npm test запускает тесты через tsx --test. Эти команды не заменяют чтение статьи глазами, но помогают не отправить в репозиторий сломанную конфигурацию, форматирование или кодовую часть проекта.

Почему не python -m http.server public

Обычный Python-сервер удобен для простых статических папок, но для этого Quartz-сайта он не подходит как основной preview. У Quartz есть clean URLs и extensionless routes. Файл может лежать как public/Кoнтакты.html, а браузер открывает /Кoнтакты.

python -m http.server public не делает нужный rewrite. Из-за этого часть страниц может выглядеть сломанной, хотя сама сборка нормальная. Чтобы не гоняться за ложными ошибками, для проверки public здесь есть tools/serve-public.ts, а для разработки — npm run site:dev.

GitHub Actions и деплой

Публикация сайта устроена так, чтобы локальная работа с Markdown не заканчивалась ручным копированием файлов на сервер. В репозитории есть два workflow.

ci.yaml запускается на pull request, push в main и вручную. Он:

ставит Node 22;
делает npm ci;
запускает npm run check;
запускает npm test;
проверяет сборку Quartz через npx quartz build --bundleInfo.

deploy.yml отвечает за публикацию:

запускается при push в main;
ставит Node 22;
делает npm ci;
собирает сайт командой npx quartz build;
публикует ./public в ветку gh-pages через peaceiris/actions-gh-pages.

Фактическая инфраструктура такая: исходники живут в main, собранный сайт появляется в public, а GitHub Pages получает готовую статику из gh-pages. Это разделяет две роли: в main редактируется проект, а наружу уходит уже собранный результат.

Осторожно с generated-каталогом библиотеки

В quartz.layout.ts вызывается generateBookshelfStaticAssets(bookshelfData). Это означает, что build может обновить:

quartz/static/generated/bookshelf-catalog.json;
quartz/static/generated/book-library-covers/*.

Эти файлы не являются ручным источником истины. Они генерируются из BOOK-LIBRARY и нужны Quartz как static fallback. Поэтому если задача касается только Markdown-статей, не стоит запускать build без необходимости: можно случайно получить лишние изменения в generated-каталоге и потом отвлекаться на то, что не относится к тексту.

Рабочий процесс для статей

Если цель простая — добавить или обновить статью, — рабочий процесс остаётся коротким и предсказуемым:

Создать или изменить Markdown-файл в content.
Заполнить frontmatter: publish, title, description, created, tags, draft, preview_image.
Проверить внутренние ссылки в формате [[Название страницы]].
Локально посмотреть через npm run site:dev, если нужно проверить внешний вид.
После коммита CI и deploy соберут сайт автоматически.

Obsidian здесь остаётся удобным редактором, но не обязательным звеном публикации. Главная логика проекта находится в репозитории, npm-скриптах и GitHub Actions. В итоге заметка проходит понятный путь: Markdown в content, локальная проверка, автоматические проверки и публикация готового сайта.

Установка и настройка Quartz 4