Profile photo
Smirnoff

5 min read

Quartz 4 в этом проекте

Quartz часто описывают как способ выложить Obsidian-vault в интернет. Это хорошая отправная точка, но для этого проекта такое описание уже слишком узкое. Здесь Quartz — основа сайта Smirnoff на домене slavx.ru: блог, проектные заметки, лендинги, контакты, юридические документы и отдельная витрина для книжной полки.

Главная ценность связки с Obsidian в том, что автор не обязан разрывать рабочий процесс на две части: отдельно писать заметки, отдельно собирать сайт. Материалы живут в content, их удобно редактировать как обычные Markdown-записи, связывать через wiki-links и раскладывать по разделам. Quartz берёт этот привычный формат и превращает его в публичный сайт, где читателю доступны навигация, поиск, превью, связанные материалы и аккуратно собранные страницы.

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

Что изменилось по сравнению с «чистым» Quartz

В старой версии этой заметки было утверждение, что Quartz работает на SvelteKit. Для текущего Quartz 4 в этом репозитории это неверный ориентир. Здесь стек ближе к статическому генератору на Node.js, TypeScript, Preact-компонентах и SCSS. На выходе получается статический сайт, который публикуется как набор файлов: текст остаётся в понятном формате, а сложность сборки прячется в конфигурации и компонентах.

Ключевые настройки лежат в quartz.config.ts:

  • pageTitle: "Smirnoff";
  • baseUrl: "slavx.ru";
  • enableSPA: true — переходы внутри сайта работают без полной перезагрузки страницы;
  • enablePopovers: true — внутренние ссылки получают всплывающие превью;
  • аналитика подключена через Plausible;
  • локаль сейчас en-US, хотя основная часть контента написана по-русски;
  • шрифты: Inter для заголовков и текста, IBM Plex Mono для кода;
  • включены RSS, sitemap, поиск, TOC, KaTeX, подсветка кода и Obsidian-flavored Markdown.

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

Контент и сайт Smirnoff

Основной контент лежит в content. Для автора это важно практически: новые материалы можно добавлять как обычные заметки, а не как отдельные сущности в админке. Раздел content/Проекты используется для проектных материалов, в том числе для серии про Obsidian и Quartz. Отдельно есть content/library.md — страница библиотеки, а также юридические документы и служебные страницы сайта.

Главная страница и контакты устроены иначе, чем обычная заметка. В quartz.layout.ts для них есть специальные исключения:

  • index получает лендинговый набор блоков из quartz/static/data/home.json;
  • Кoнтакты собираются из quartz/static/data/contacts.json;
  • library рендерится через компонент LibraryPage и данные bookshelf.json.

Это удобный компромисс: тексты и страницы остаются в Quartz, но сложные экраны можно собирать из JSON-данных и компонентов, не превращая Markdown в кашу из HTML. Читатель видит цельную страницу, а автор сохраняет нормальную структуру материалов.

Навигация: не стандартный Explorer

В левой колонке вместо обычного Explorer используется CardMenu. Это не декоративная замена, а попытка сделать навигацию ближе к реальному сайту: человеку проще выбрать раздел или служебную страницу, не разбираясь в полном дереве vault. Сейчас рядом с ним стоит Avatar, а на мобильных появляется компактная панель с поиском, переключателем темы и режимом чтения.

CardMenu строит меню по дереву файлов, умеет сворачивать папки, сохранять состояние в localStorage, показывает навигационные кнопки и поддерживает дополнительный drawerComponent. В текущих настройках есть кнопки:

  • Контакты;
  • RSS;
  • Архив.

Это уже не черновой эксперимент с меню, а фактическая навигация сайта: она помогает читателю быстро понять, куда идти дальше, а не оставляет его один на один со списком файлов.

Карточки превью и списки

Для страниц папок и тегов включён режим usePreviewList. Его используют эмиттеры FolderPage и TagPage в quartz.config.ts. Вместо сухого списка ссылок сайт показывает карточки с заголовком, описанием, датой, тегами и картинкой из preview_image. Так обзор раздела становится похож на витрину материалов: можно быстро понять, о чём статья и стоит ли открывать её сейчас.

Картинка берётся из frontmatter статьи. Компонент PagePreviewList резолвит путь через resolveRelative, поэтому абсолютные пути вида /images/example.png и относительная навигация проходят через одну механику Quartz.

Custom OG images

В проекте включён CustomOgImages с шаблоном smirnoffSocialImage. Это нужно, чтобы страницы красиво выглядели при шаринге. Но у этой функции есть цена: генерация изображений может заметно замедлять build. В конфиге прямо оставлен комментарий, что emitter можно временно отключить, если нужно ускорить сборку.

Библиотека внутри Quartz

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

  • content/library.md задаёт страницу;
  • LibraryPage рендерит интерфейс;
  • bookshelf.json хранит backend URL и путь к static catalog;
  • bookshelfCatalog.ts на build-time может подготовить generated catalog и mirrored covers;
  • клиентский скрипт умеет использовать live API и fallback к статическому каталогу.

Важно: generated-файлы библиотеки не редактируются руками. Они побочный результат сборки и синхронизации с BOOK-LIBRARY. За счёт этого страница остаётся частью сайта, но данные не приходится дублировать в Markdown вручную.

Где Quartz здесь особенно полезен

Quartz хорошо подошёл этому сайту не потому, что он «лучший способ» публиковать заметки. Такая формулировка звучит рекламно и ничего не объясняет.

В этом проекте он полезен по другой причине: можно держать рядом статьи, проектные документы, лендинговые страницы, граф связей, поиск, RSS и кастомные компоненты. Markdown остаётся понятным источником текста, а TypeScript-компоненты закрывают места, где обычной заметки уже мало.

Для автора это решает понятную проблему: знания, черновики и проектные описания не застревают внутри личного vault, но и не превращаются в отдельный тяжёлый сайт, который нужно обслуживать отдельно от текстов. Для читателя это даёт другой результат — не папку случайных заметок, а связанный сайт, где можно читать материалы, переходить по темам и видеть контекст.

Если коротко: Quartz здесь — статический каркас сайта Smirnoff, а не просто экспорт Obsidian в веб.

Связанные материалы

Graph View

Backlinks