Создание сайта с помощью Quartz 4

Генератор статического сайта Quartz позволяет на базе хранилища (vaiult) редактора/приложения для ведения базы знаний Obsidian сгенерировать статичный web-сайт (набор html, css, xml, js и других сопутствующих файлов). Сгенерированный сайт далее можно залить на любой хостинг. После любого обновления контента сайт нужно генерировать заново.

Площадка GitHub позволяет с использованием GitHuab Actions автоматизировать процесс генерации и выполнять его непосредственно на самой площадке при любом обновлении репозитория. Сам сайт при этом публикуется с помощью GitHub Pages.

Российская платформа для хранения Git-репозиториев GitFlic пока таких возможностей не предоставляет.

Ниже приведена пошаговая инструкция по созданию сайта с помощью Quartz с применением GitFlic, GitHub и Obsidian.

В инструкции рассмотрен пример запуска сайта по адресу https://hub.zlonov.ru с использованием закрытого (приватного репозитория) с файлами самого Quartz и дополнительными служебными файлами на GitHub: https://github.com/zlonov/hub.zlonov.ru и открытого репозитория с контентом на GitFlic: https://gitflic.ru/project/zlonov/hub .

Используемые названия

В командах ниже используются конкретные названия папок, хранилищ и репозиториев. Их нужно поменять на ваши собственные:

• Локальная папка с репозиторием Quartz:  ~/Git/hub.zlonov.ru.
• Локальная папка с репозиторием для контента:  ~/Library/Mobile\ Documents/iCloud\~md\~obsidian/Documents/Digital.Garden/hub/, что соответствует пути iCloud Drive/Obsidian/Digital.Garden/hub/ в файловом менеджере.
• Удалённый репозиторий для Quartz: https://github.com/zlonov/hub.zlonov.ru.git
• Удалённый репозиторий для контента: https://gitflic.ru/project/zlonov/hub.git
• Сайт с результатом: https://hub.zlonov.ru

В качественной операционной системы используется macOS Ventura, в других системах пути и команды могут отличаться.

Предварительные настройки

Как указано на сайте разработчиком: Quartz requires at least Node v20 and npm v9.3.1 to function correctly. Процесс установки описан тут: Node download page .

# installs nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# download and install Node.js (you may need to restart the terminal)
nvm install 20

# verifies the right Node.js version is in the environment
node -v # should print `v20.17.0`

# verifies the right npm version is in the environment
npm -v # should print `10.8.2`

Инициализация Quartz

Будем создавать сайт, сохраняя локальную копию репозитория Quartz в пользовательской папке ~/Git/hub.zlonov.ru. Предполагается, что папка Git уже создана ранее. Второй параметр (hub.zlonov.ru) команды git clone устанавливает папку, в которую будет клонирован репозиторий. По умолчанию, если не указать второй параметр, в качестве названия папки для клонирования будет использовано имя самого репозитория (quartz).

cd ~/Git  
git clone https://github.com/jackyzha0/quartz.git hub.zlonov.ru
cd hub.zlonov.ru
npm i
npx quartz create

Если выдаётся предупреждение о найденных уязвимостях:

3 vulnerabilities (1 moderate, 2 high) To address all issues, run:   npm audit fix

Можно их исправить:

npm audit fix

Опции, предлагаемые после запуска последней команды, можно выбрать дефолтные:

• ● Empty Quartz
• ● Treat links as shortest path ((default))

Посмотреть на получившийся результат можно сразу, запустив локальную версию сайта:

npx quartz build --serve

Сайт будет доступен по ссылке: http://localhost:8080/. Прервать работу локальной версии сайта можно в любой момент сочетанием клавиш ctrl+c в терминале.

Создание удалённых репозиториев

Теперь нам нужны два удалённых репозитория - в одном (приватном) будет храниться код самого Quartz, а в другом (публичном) - контент. Так будем делать для удобства - любой сможет сделать клон контента и работать с ним самостоятельно в Obsidian. Дополнительно так можно увеличить доступное именно для контента дисковое пространство, если тариф выбранной площадки от этого зависит, так как файлы самого движка/генератора сайта Quartz и дополнительные файлы будут храниться в отдельно.

В принципе, можно оставить файлы Quartz (или даже и контент) только локально. Публиковать (на хостинге) можно только сам сгенерированный статичный сайт. Удобство удалённых репозиториев в полной мере раскрывается, когда:

• есть потребность работы одновременно с разных рабочих мест и не хочется каждый раз думать о проблемах с синхронизацией;
• есть необходимость ведения работы в команде;
• присутствует желание сделать часть своей работы (или всю её) публично доступной;
• хочется дать другим людям возможность предлагать правки (через pull request).

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

Бесплатный тариф GitFlic позволяет хранить в одном репозитории до 4 ГБ - это есть смысл учесть при оценке масштабов предстоящего сайта.

Удалённый репозиторий на GitFlic для контента

Входим в свой аккаунт (или сначала регистрируемся) и создаём новый публичный проект:

• Название проекта: hub
• Описание проекта: Контент для hub.zlonov.ru
• URL проекта: https://gitflic.ru/project/zlonov/hub
• Тип проекта: ● Публичный проект

Ссылка на репозиторий будет такой: https://gitflic.ru/project/zlonov/hub.git

Удалённый репозиторий на GitHub для Quartz

Входим в свой аккаунт (или сначала регистрируемся) и создаём новый репозиторий: - Repository name: hub.zlonov.ru - Тип: ● Private Больше ничего не меняем и нажимаем Create repository.

Ссылка на репозиторий будет такой: https://github.com/zlonov/hub.zlonov.ru.git

Создание хранилища Obsidian из удалённого репозитория

Так как контент мы решили отделить от файлов Quartz, то для его (контента) хранения будем использовать удобную нам папку. В случае с экосистемой Apple удобнее разместить папку непосредственно в iCloud Drive - так контент будет доступен на всех устройствах с одним и тем же Apple ID и при этом автоматически синхронизироваться. Каких-либо проблем при размещении хранилища Obsidian в iCloud Drive за всё время использования не возникало.

Переходим в желаемую папку и клонируем туда наш репозиторий для контента:

cd ~/Library/Mobile\ Documents/iCloud\~md\~obsidian/Documents
cd Digital.Garden
git clone https://gitflic.ru/project/zlonov/hub.git hub

В рассматриваемом примере папка с контентом hub хранится внутри другого хранилища Obsidian - Digital.Garden. Такой подход удобен, когда вы хотите работать в одном запущенном окне Obsidian сразу и с контентом, публикуемым на сайте, и с другими своими заметками, которые не планируете делать публичными. Всё публичное будет находиться просто в отдельной собственной папке hub внутри хранилища Obsidian Digital.Garden. При этом будут работать все внутренние ссылки, а граф связей строится единый. Важно только следить, чтобы не возникала путаница при использовании одинаковых названий заметок - желательно стремиться, чтобы они оставались уникальными.

На появляющееся после клонирования предупреждение warning: You appear to have cloned an empty repository. можно не обращать внимания - репозиторий пока действительно пустой.

Теперь нам надо запустить Obsidian и открыть папку hub либо как отдельное хранилище либо в хранилище Digital.Garden. В корне hub надо создать заметку index либо можно просто скопировать файл index.md из папки созданного выше локального репозитория: ~/Git/hub.zlonov.ru/content/. Содержимое заметки index.md будет являться заглавной (домашней) страницей создаваемого сайта.

Дефолтный index.md выглядит так:

---
title: Welcome to Quartz
---

This is a blank Quartz installation.
See the [documentation] for how to get started.

Синхронизация локальных изменений репозитория с контентом с удалённым репозиторием

Переходим в локальный клон репозитория.

cd ~/Library/Mobile\ Documents/iCloud\~md\~obsidian/Documents/Digital.Garden/hub

Добавляем все файлы в отслеживаемые:

git add .

Убеждаемся, что нужный нам файл index.md проиндексирован:

git status

Он должен оказаться в разделе “Changes to be committed”:

On branch main
No commits yet
Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
new file:   index.md

Коммитим (вносим) изменения, указав комментарий к нему сразу в командной строке, и отправляем их в удалённый репозиторий:

git commit -m "Первый коммит"
git push

Примерный результат будет такой:

[main (root-commit) 059b19f] Первый коммит
 1 file changed, 4 insertions(+)
 create mode 100644 index.md
Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Delta compression using up to 12 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 485 bytes | 485.00 KiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
remote: Updating references: 100% (1/1)
To https://gitflic.ru/project/zlonov/hub.git
 * [new branch]      main -> main

Можно убедиться, что по ссылке https://gitflic.ru/project/zlonov/hub/file появился наш файл index.md.

Подключение удалённого репозитория Quartz к локальному

Переходим в локальную папку с инициированным репозиторием Quartz:

cd ~/Git/hub.zlonov.ru/

Проверяем все отслеживаемые репозитории:

git remote -v

Результат будет примерно таким:

origin https://github.com/jackyzha0/quartz.git (fetch)
origin https://github.com/jackyzha0/quartz.git (push)
upstream https://github.com/jackyzha0/quartz.git (fetch)
upstream https://github.com/jackyzha0/quartz.git (push)

Нам надо поменять origin на наш собственный репозиторий, ссылку на который мы получили на предыдущем этапе:

git remote set-url origin https://github.com/zlonov/hub.zlonov.ru.git

Если вдруг в качестве upstream не установлен репозиторий Quartz, добавим его, чтобы обновления самого Quartz работали:

git remote add upstream https://github.com/jackyzha0/quartz.git

Проверяем все отслеживаемые репозитории ещё раз:

git remote -v

Результат должен быть примерно таким:

origin https://github.com/zlonov/hub.zlonov.ru.git (fetch)
origin https://github.com/zlonov/hub.zlonov.ru.git (push)
upstream https://github.com/jackyzha0/quartz.git (fetch)
upstream https://github.com/jackyzha0/quartz.git (push)

Теперь можно синхронизировать контент и загрузить его в свой репозиторий. Данная команда выполнит первоначальную отправку контента:

npx quartz sync --no-pull

Вывод результата работы команды должен быть примерно таким:

 Quartz v4.2.3 
Backing up your content
[v4 cd15cda] Quartz sync: Mar 4, 2024, 10:38 AM
 2 files changed, 6 insertions(+)
 delete mode 100644 content/.gitkeep
 create mode 100644 content/index.md
Pushing your changes
Enumerating objects: 8388, done.
Counting objects: 100% (8388/8388), done.
Delta compression using up to 12 threads
Compressing objects: 100% (3027/3027), done.
Writing objects: 100% (8388/8388), 6.33 MiB | 9.22 MiB/s, done.
Total 8388 (delta 5277), reused 8360 (delta 5253), pack-reused 0
remote: Resolving deltas: 100% (5277/5277), done.
To https://github.com/zlonov/hub.zlonov.ru.git
 * [new branch]      v4 -> v4
branch 'v4' set up to track 'origin/v4'.
Done!

В удалённом репозитории теперь появятся файлы самого Quartz и папка content c нашим файлом index.md: https://github.com/zlonov/hub.zlonov.ru

Для дальнейшей синхронизации можно пользоваться либо командой npx quartz sync либо Git-клиентом.

Подключение репозитория с контентом в качестве подмодуля

Итак, репозиторий с контентом hub теперь находится в локальном хранилище Obsidian, с помощью которого можно (и нужно) его редактировать. Он синхронизируется средствами Git с удалённым репозиторием на площадке GitFlic: https://gitflic.ru/project/zlonov/hub/.

Сам же Quartz у нас локально установлен в папке ~/Git/hub.zlonov.ru и синхронизируется с удалённым репозиторием https://github.com/zlonov/hub.zlonov.ru.git.

При генерации статичного сайта Quartz использует файлы, находящиеся в папке ~/Git/hub.zlonov.ru/content/, поменяем теперь настройки так, чтобы использовалась папка из репозитория https://gitflic.ru/project/zlonov/hub.git. Для этого надо подключить этот репозиторий в качестве подмодуля к репозиторию самого Quartz.

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

Сначала удаляем папку content и отправляем изменения в удалённый репозиторий:

cd ~/Git/hub.zlonov.ru
rm -rf content
git add .
git commit -m "Удалена папка content"
git push

Теперь создаём подмодуль командой git submodule add, указвая путь к публичному репозиторию с контентом:

git submodule add https://gitflic.ru/project/zlonov/hub.git content

Если всё сделано правильно, в командной строке появится примерно такой текст:

Cloning into '/Users/zlonov/Git/hub.zlonov.ru/content'...
remote: Counting objects: 3, done
remote: Finding sources: 100% (3/3)
remote: Getting sizes: 100% (2/2)
remote: Total 3 (delta 0), reused 3 (delta 0)
Receiving objects: 100% (3/3), 485 bytes | 485.00 KiB/s, done.

В результате в репозитории ~/Git/hub.zlonov.ru будет создана папка content и файл .gitmodules такого содержания:

[submodule "content"]
	path = content
	url = https://gitflic.ru/project/zlonov/hub.git

Эти изменения нужно отправить в удалённый репозиторий:

git add .
git commit -m "Создан подмодуль content"
git push

После успешного завершения в удалённом репозитории ( https://github.com/zlonov/hub.zlonov.ru ) можно будет увидеть, что у папки content изменилась иконка - теперь это папка со стрелочкой, что означает, что в качестве её содержимого используются файлы из другого репозитория, ставшего подмодулем.

Синхронизация репозитория с подмодулем

Так как папка с контентом content теперь является отдельным репозиторием, сначала все вносимые изменения надо коммитить в нём. Далее для основного репозитория, для которого репозиторий с контентом является подмодулем, нужно будет выполнять команду проверки и обновления:

git submodule update --remote --merge

Можно заменить эту длинную команду на короткий псевдоним (alias):

git config alias.sup 'submodule update --remote --merge'

Теперь вместо длинной команды можно писать просто:

git sup

Алгоритм обновления репозитория https://github.com/zlonov/hub.zlonov.ru с подмодулем https://gitflic.ru/project/zlonov/hub будет таким:

1. Вносим изменения в папке с контентом средствами Obsidian;
2. Коммитим изменения в репозитории с контентом (как вариант, выполняем в Git-клиенте для репозитория с контентом команды Git-клиента: Commit to master и Push);
3. Обновляем репозиторий с учётом изменений подмодуля git sup
4. Выполняем git commit -a -m "Обновление контента" (благодаря опции -a не нужно выполнять git add ИМЯ.ФАЙЛА) и отправляем изменения на сервер git push либо, как вариант, выполняем в Git-клиенте для репозитория с Quartz команды: Commit to v4 и Push.

Для упрощения выполнения команд из пунктов 3 и 4 можно создать короткий псевдоним git config alias.up '!git submodule update --remote --merge && git commit -a -m "Update content" && git push' и далее использовать его: git up.

Настройка хостинга GitHub Pages

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

В папке репозитория ~/Git/hub.zlonov.ru нужно создать новый файл /.github/workflows/deploy.yml с содержимым как ниже. Важно добавить проверку подмодулей - строка submodules: true ниже:

name: Deploy Quartz site to GitHub Pages
 
on:
  push:
    branches:
      - v4
 
permissions:
  contents: read
  pages: write
  id-token: write
 
concurrency:
  group: "pages"
  cancel-in-progress: false
 
jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0 # Fetch all history for git info
          submodules: true
      - uses: actions/setup-node@v3
        with:
          node-version: 18.14
      - name: Install Dependencies
        run: npm ci
      - name: Build Quartz
        run: npx quartz build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v2
        with:
          path: public
 
  deploy:
    needs: build
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

Переходим в настройках репозитория (вкладка Settings) в настройки страницы (пункт Pages в боковом меню) и в настройке Source выбираем GitHub Actions.

Отправляем изменения в удалённый репозиторий:

git add . && git commit -a -m "GitHub Actions" && git push

Или пользуемся командами Git-клиента: Commit to v4 и Push.

Можно посмотреть как выполняются Actions и при необходимости перезапустить их: https://github.com/zlonov/hub.zlonov.ru/actions/

По завершению сайт будет доступен по адресу <github-username>.github.io/<repository-name> ( https://zlonov.github.io/hub.zlonov.ru/ )

Дополнение для варианта с приватным репозиторийем в качестве подмодуля. Нужно:

• создать токен (PAT)
• создать новый секрет в настройках основного репозитория https://github.com/zlonov/quartz-hub.zlonov.ru/settings/secrets/actions/new с именем, например, GH_PAT
• добавить строчку с указанием в качестве токена секрета GH_PAT:

jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
        with:
          token: ${{ secrets.GH_PAT }}
          fetch-depth: 0 # Fetch all history for git info
          submodules: recursive

Настройка собственного доменного имени для Github Pages

Подробности по настройке тут: GitHub Pages custom domain .

Настройка Quartz

Подробности по настройке тут: Quartz 4 initial site configuration .