Profile photo
Smirnoff

7 min read

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

Quartz + Obsidian позволяют превратить локальные заметки в полноценный статический сайт, который автоматически публикуется на GitHub Pages. Ниже — пошаговое руководство, основанное на реальных проблемах и их решениях.

Часть 1 — Начальная установка Quartz (шаг за шагом)

1. Подготовка окружения

Понадобится:

  • Git
  • Node.js (вместе с npm)
  • Аккаунт GitHub
  • Obsidian

Установи их заранее (Git for Windows, Node.js LTS, Obsidian с официального сайта).

2. Клонирование Quartz

Создай папку для проекта и клонируй Quartz:

git clone https://github.com/jackyzha0/quartz.git D:\Project\Quartz\quartz
cd D:\Project\Quartz\quartz

В результате у тебя появится структура:

D:\Project\Quartz\quartz\
  ├─ .github\
  ├─ content\          (может использоваться по умолчанию, но мы вынесем контент отдельно)
  ├─ quartz.config.ts
  ├─ package.json
  └─ ...

3. Установка зависимостей

Внутри папки проекта:

cd D:\Project\Quartz\quartz
npm install

Это подтянет все зависимости, необходимые для сборки и запуска сайта.

4. Создание папки для контента

Рекомендуется вынести контент (заметки) в отдельную папку, которая будет одновременно:

  • Obsidian-вольтом;
  • источником markdown-файлов для Quartz.

Например:

mkdir D:\lopolama\content

5. Создание главной страницы index.md

В корне папки контента создаётся файл index.md:

D:\lopolama\content\index.md:

---
title: Welcome to My Digital Garden
description: My personal notes and thoughts
---
 
# Welcome! 👋
 
Это мой цифровой сад на базе **Quartz** и Obsidian.
 
## Последние заметки
 
Загляните в раздел с заметками, там появляются новые статьи.
 
---
 
_Last updated: 2025-12-16_

Этот файл критически важен:

  • это главная страница сайта;
  • на его основе (и его структуре/ссылках) часто строится меню и навигация.

6. Привязка Obsidian к папке контента

В Obsidian:

  1. Открыть Obsidian.
  2. Нажать Open folder as vault.
  3. Выбрать D:\lopolama\content.

Теперь все файлы внутри D:\lopolama\content — это твой Obsidian-вольт, а заодно — источник для Quartz.

Часть 2 — Настройка Publication Center (что это, как установить)

Что такое Publication Center / Quartz Syncer

Это плагин Obsidian, который:

  • позволяет управлять публикацией заметок в отдельном интерфейсе;
  • добавляет/убирает флаг publish: true в YAML-фронтматтере файла;
  • синхронизирует изменения с GitHub (push-ит в репозиторий, который использует Quartz).

Фактически, это «панель публикаций» между Obsidian и GitHub.

Установка плагина в Obsidian

  1. Открыть Settings → Community plugins.
  2. Включить Community plugins (если ещё выключен Safe mode).
  3. Нажать Browse.
  4. Найти плагин, например Quartz Syncer / Publication Center (название может отличаться в зависимости от конкретной реализации).
  5. Нажать Install, затем Enable.

Первоначальная настройка

В настройках плагина (обычно Settings → Plugin options → Quartz / Publication Center):

  • указать GitHub репозиторий (например, username/Quartz);
  • задать ветку (обычно main или master);
  • добавить GitHub токен с правами на repo (создаётся в GitHub → Settings → Developer settings → Personal access tokens).

После этого плагин сможет:

  • считывать изменённые файлы;
  • пушить изменения в указанный репозиторий;
  • отмечать, какие файлы опубликованы, а какие нет.

Часть 3 — Правильная структура проекта

Рекомендуемая структура:

D:\Project\Quartz\quartz\
├── .github\
├── public\
├── quartz.config.ts
├── package.json
└── ... (код и конфигурация Quartz)
 
D:\lopolama\content\
├── index.md             ← главная страница
├── notes\
│   ├── Quartz-Setup.md  ← будущая статья о настройке
│   ├── Article1.md
│   └── Article2.md
└── images\
    └── ...

Ключевые моменты:

  • D:\Project\Quartz\quartz — код сайта, сборка, GitHub Actions.
  • D:\lopolama\content — вольт Obsidian и источник markdown-контента.
  • index.md — всегда присутствует; без него легко получить пустую или некорректную навигацию.
  • Папка notes/ (и другие) — для статей, тут лежат публикации.

Часть 4 — Решение типичных проблем

Проблема 1: Статьи есть, но меню не обновляется

Сценарий:

  • новую статью опубликовали через Publication Center;
  • файл успешно залился на GitHub;
  • статья открывается по прямой ссылке;
  • но в меню/на главной её нет.

Это часто связано с кэшем, состоянием index.md или тем, как Quartz собирает навигацию.

Рабочее решение, проверенное на практике:

  1. В Obsidian открыть index.md.

  2. В Publication Center нажать Unpublish на index.md.

  3. Внести небольшое изменение в файл, например:

    • обновить дату внизу;
    • добавить/убрать пробел;
    _Last updated: 2025-12-16_ ← изменить на актуальную

  4. Сохранить файл (Ctrl+S).

  5. В Publication Center нажать Publish для index.md.

  6. Подождать 2–3 минуты, пока GitHub Actions пересоберёт сайт.

  7. Обновить страницу сайта с принудительным сбросом кеша: Ctrl+Shift+R.

Почему это работает:

  • Unpublish убирает флаг публикации и меняет состояние файла;
  • изменение содержимого делает файл «новой версией»;
  • повторный Publish создаёт новый коммит, который заставляет Quartz и GitHub Actions пересчитать всё, включая меню.

Проблема 2: index.md не существует

Симптомы:

  • сайт открывается, но:
    • нет нормальной главной страницы;
    • нет меню;
  • иногда отображается только список или пустая страница.

Решение:

  1. Проверить, существует ли D:\lopolama\content\index.md.

  2. Если файл отсутствует — создать:

    ---
title: Welcome to My Digital Garden
description: My personal notes and thoughts
---
 
# Welcome! 👋
 
Это мой цифровой сад.
 
## Последние заметки
 
(здесь может быть список ссылок или автогенерация меню)
 
---
 
_Last updated: 2025-12-16_

  3. Сохранить файл.

  4. Опубликовать index.md через Publication Center.

  5. Подождать 2–3 минуты, обновить сайт.

Проблема 3: Изменения не появляются на сайте

Симптомы:

  • файл изменён в Obsidian;
  • в Publication Center нажали Publish;
  • на сайте видна старая версия.

Порядок проверки:

  1. Убедиться, что файл действительно сохранён (Ctrl+S в Obsidian).
  2. Проверить, что Publication Center сделал push:
    • зайти на GitHub в репозиторий;
    • убедиться, что есть свежий коммит.
  3. Проверить GitHub Actions:
    • вкладка Actions в репозитории;
    • посмотреть, прошёл ли workflow без ошибок.
  4. В браузере сделать Ctrl+Shift+R (жёсткое обновление без кеша).
  5. Если всё ещё не видно:
    • подождать 3–5 минут;
    • обновить ещё раз.

Часть 5 — Правильный рабочий процесс

Публикация одной новой статьи

  1. В Obsidian (в D:\lopolama\content) создать файл, например: notes\Quartz-Setup.md.
  2. Написать текст статьи.
  3. Сохранить файл (Ctrl+S).
  4. Открыть Publication Center.
  5. Поставить галочку / нажать Publish на этой заметке.
  6. Подождать 2–3 минуты.
  7. Открыть сайт и обновить страницу (Ctrl+Shift+R).

Статья появится на сайте. Если нужно, добавить ссылку на неё в index.md.

Обновление меню / навигации через index.md

Когда добавляешь новые разделы/ссылки в меню:

  1. Открыть index.md.
  2. Добавить нужные ссылки/блоки (например, список разделов или ссылок на новые статьи).
  3. Сохранить файл.
  4. В Publication Center:
    • при проблемах с обновлением меню — сделать Unpublish → Publish для index.md;
    • при нормальной работе — достаточно обычного Publish.
  5. Подождать 2–3 минуты.
  6. Обновить сайт (Ctrl+Shift+R).

Часть 6 — Полезные советы (шаблоны, структурирование, линковка)

Совет 1: Шаблон новой статьи

Чтобы не писать фронтматтер руками, удобно завести шаблон в Obsidian (через плагин Templater или встроенные Templates):

---
title: { { title } }
description: { { description } }
tags:
  - note
publish: false
date: { { date } }
---
 
# {{title}}
 
## Введение
 
## Основной контент
 
## Заключение
 
---
 
_Создано: {{date}}_

Плюсы:

  • все статьи имеют единообразный формат;
  • заранее есть поля для описания, тегов и даты;
  • publish: false по умолчанию → публикацию контролируешь через Publication Center.

Совет 2: Структурирование заметок по папкам

Рекомендуется развести заметки по тематическим папкам:

content\
├── index.md
├── notes\
│   ├── tutorials\
│   │   ├── Obsidian-Guide.md
│   │   └── Git-Basics.md
│   ├── thoughts\
│   │   └── Digital-Garden.md
│   └── tech\
│       └── Quartz-Setup.md
└── images\
    └── ...

Так:

  • легче ориентироваться в Obsidian;
  • Quartz читает всё дерево, так что структура сохранится логично.

Совет 3: Линковка между статьями

В Obsidian стандартный способ связи — wiki-links:

См. также: [[Obsidian-Guide]] и [[Git-Basics]].

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

Совет 4: Метаданные в YAML

YAML-фронтматтер можно использовать не только для title и description, но и для:

---
title: My Article
description: Short description for preview
tags:
  - programming
  - tutorial
publish: true
date: 2025-12-16
---

Это помогает:

  • фильтровать заметки;
  • генерировать списки по тегам;
  • отображать дату и теги на сайте.

Часть 7 — Развёртывание на GitHub Pages

1. Репозиторий на GitHub

Есть два распространённых варианта:

  • Отдельный репозиторий для сайта, например username/Quartz.
  • Репозиторий формата username.github.io, если хочешь сайт на корневом домене.

Минимум:

  1. Создать репозиторий на GitHub.
  2. Запушить туда содержимое D:\Project\Quartz\quartz.

Если Publication Center уже пушит в этот репозиторий — часть настроек уже сделана.

2. GitHub Actions

В Quartz обычно уже есть конфигурация workflow в .github/workflows. Проверить:

  • в репозитории на GitHub есть папка .github/workflows;
  • внутри — файл сборки, например deploy.yml / build.yml.

Этот файл:

  • устанавливает Node.js;
  • выполняет npm install, npm run build;
  • выкладывает статические файлы в нужную ветку (например, gh-pages или main / docs).

3. Настройка GitHub Pages

В репозитории:

  1. Перейти Settings → Pages.
  2. В разделе Build and deployment выбрать:
    • источник: GitHub Actions (если всё через workflow) или
    • branch: gh-pages / main и директория / (root) или /docs (в зависимости от настройки Quartz).
  3. Сохранить.

Через пару минут GitHub Pages выкатит сайт по адресу:

https://username.github.io/Quartz/

или

https://username.github.io/

в зависимости от конфигурации.

🚀 Как опубликовать эту статью

  1. Скопировать содержимое этой статьи целиком.

  2. В Obsidian (вольт D:\lopolama\content) создать файл:

    D:\lopolama\content\notes\Quartz-Setup.md

  3. Вставить содержимое.

  4. Сохранить файл (Ctrl+S).

  5. Открыть Publication Center.

  6. Нажать Publish для Quartz-Setup.md.

  7. Подождать 2–3 минуты.

  8. Открыть сайт, обновить страницу (Ctrl+Shift+R).

После этого статья появится на сайте, и её можно добавить в меню/на главную через правку index.md.

После успешной установки вы можете перейти к настройке внешнего вида вашего сайта, чтобы сделать его уникальным.

Graph View

Backlinks