Ниже приведена пошаговая инструкция по созданию сайта с помощью генератора статических сайтов Quartz, применением платформ для хранения Git-репозиториев GitFlic, GitHub и редактора/приложения для ведения базы знаний Obsidian.
В командах ниже используются конкретные названия папок, хранилищ и репозиториев. Их нужно поменять на ваши собственные:
Локальная папка с репозиторием Quartz: ~/Git/hub.zlonov.ru.
Локальная папка с репозиторием для контента: ~/Library/Mobile\ Documents/iCloud\~md\~obsidian/Documents/Zettelkästen/hub/, что соответствует пути iCloud Drive/Obsidian/Zettelkästen/hub/ в файловом менеджере.
В качественной операционной системы используется macOS Ventura, в других системах пути и команды могут отличаться.
Инициализация 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.rucd hub.zlonov.runpm inpx quartz create
Опции, предлагаемые после запуска последней команды, можно выбрать дефолтные:
● 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 для контента
Входим в свой аккаунт (или сначала регистрируемся) и создаём новый публичный проект:
Входим в свой аккаунт (или сначала регистрируемся) и создаём новый репозиторий:
- Repository name: hub.zlonov.ru
- Тип: ● Private
Больше ничего не меняем и нажимаем Create repository.
Подсказка
На GitHub в названиях репозиториев можно использовать точки.
Ссылка на репозиторий будет такой: https://github.com/zlonov/k0mar0v.ru.git
Создание хранилища Obsidian из удалённого репозитория
Так как контент мы решили отделить от файлов Quartz, то для его (контента) хранения будем использовать удобную нам папку. В случае с экосистемой Apple удобнее разместить папку непосредственно в iCloud Drive - так контент будет доступен на всех устройствах с одним и тем же Apple ID и при этом автоматически синхронизироваться. Каких-либо проблем при размещении хранилища Obsidian в iCloud Drive за всё время использования не возникало.
Переходим в желаемую папку и клонируем туда наш репозиторий для контента:
cd ~/Library/Mobile\ Documents/iCloud\~md\~obsidian/Documentscd Zettelkästengit clone https://gitflic.ru/project/zlonov/hub.git hub
В рассматриваемом примере папка с контентом hub хранится внутри другого хранилища Obsidian - Zettelkästen. Такой подход удобен, когда вы хотите работать в одном запущенном окне Obsidian сразу и с контентом, публикуемым на сайте, и с другими своими заметками, которые не планируете делать публичными. Всё публичное будет находиться просто в отдельной собственной папке hub внутри хранилища Obsidian Zettelkästen. При этом будут работать все внутренние ссылки, а граф связей строится единый. Важно только следить, чтобы не возникала путаница при использовании одинаковых названий заметок - желательно стремиться, чтобы они оставались уникальными.
На появляющееся после клонирования предупреждение warning: You appear to have cloned an empty repository. можно не обращать внимания - репозиторий пока действительно пустой.
Теперь нам надо запустить Obsidian и открыть папку hub либо как отдельное хранилище либо в хранилище Zettelkästen. В корне 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.
Синхронизация локальных изменений репозитория с контентом с удалённым репозиторием
Подсказка
Ниже приведены команды для Терминала, но для удобства можно использовать какой-либо клиент (редактор) Git с графическим интерфейсом: Git GUI clients.
Если будут какие-либо сложности с правами доступа (например, fatal: unable to access или/и The requested URL returned error: 403), для разрешения которых опыта работы с Git через командную строку пока недостаточно, то проще воспользоваться клиентом Git с графическим интерфейсом: Git GUI clients. Необходимые права доступы они обычно самостоятельно умеют запрашивать и кэшировать для дальнейшего использования.
В Git-клиент нужно добавить наш репозиторий через Add Existing Repository... или подобную команду меню, для которой указать путь к iCloud Drive/Obsidian/Zettelkästen/hub/.
Подсказка
Дальнейшую синхронизацию можно продолжать выполнять через команды для Терминала, но для удобства можно использовать какой-либо клиент (редактор) Git с графическим интерфейсом: Git GUI clients.
В Git-клиент нужно добавить наш репозиторий через Add Existing Repository... или подобную команду меню, для которой указать путь к iCloud Drive/Obsidian/Zettelkästen/hub/.
Удобство клиента, помимо наглядности, в том числе в автоматическом запросе и сохранении на будущее данных учётной записи для доступа к удалённому репозиторию.
Подключение удалённого репозитория Quartz к локальному
Дальнейшую синхронизацию можно продолжать выполнять через команды для Терминала, но для удобства можно использовать какой-либо клиент (редактор) Git с графическим интерфейсом: Git GUI clients.
В Git-клиент нужно добавить наш репозиторий через Add Existing Repository... или подобную команду меню, для которой указать путь к ~/Git/hub.zlonov.ru/.
Удобство клиента, помимо наглядности, в том числе в автоматическом запросе и сохранении на будущее данных учётной записи для доступа к удалённому репозиторию.
Теперь можно синхронизировать контент и загрузить его в свой репозиторий. Данная команда выполнит первоначальную отправку контента:
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!
Для дальнейшей синхронизации можно пользоваться либо командой 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 и отправляем изменения в удалённый репозиторий:
После успешного завершения в удалённом репозитории (https://github.com/zlonov/hub.zlonov.ru) можно будет увидеть, что у папки content изменилась иконка - теперь это папка со стрелочкой, что означает, что в качестве её содержимого используются файлы из другого репозитория, ставшего подмодулем.
Синхронизация репозитория с подмодулем
Так как папка с контентом content теперь является отдельным репозиторием, сначала все вносимые изменения надо коммитить в нём. Далее для основного репозитория, для которого репозиторий с контентом является подмодулем, нужно будет выполнять команду проверки и обновления:
Вносим изменения в папке с контентом средствами Obsidian;
Коммитим изменения в репозитории с контентом (как вариант, выполняем в Git-клиенте для репозитория с контентом команды Git-клиента: Commit to master и Push);
Обновляем репозиторий с учётом изменений подмодуля git sup
Выполняем 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.
Так как в качестве 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.
Чтобы использовать GitHub pages для публикации своего сайта нужно:
Перейти в Settings своего репозитория.
В разделе Code and automation в боковом меню выбрать Pages.
В поле Custom Domain, написать адрес своего домена и нажать Save.
Следующие шаги зависят от используемого домена - Apex (example.com) или Subdomain (subdomain.example.com).
If you are using an apex domain, navigate to your DNS provider and create an A record that points your apex domain to GitHub’s name servers which have the following IP addresses:
185.199.108.153
185.199.109.153
185.199.110.153
185.199.111.153
If you are using a subdomain, navigate to your DNS provider and create a CNAME record that points your subdomain to the default domain for your site. For example, if you want to use the subdomain quartz.example.com for your user site, create a CNAME record that points quartz.example.com to <github-username>.github.io.
hub.zlonov.ru. 3600 IN CNAME zlonov.github.io.
zlonov.github.io. 3600 IN A 185.199.108.153
zlonov.github.io. 3600 IN A 185.199.111.153
zlonov.github.io. 3600 IN A 185.199.109.153
zlonov.github.io. 3600 IN A 185.199.110.153
k0mar0v.ru. 3547 IN A 185.199.111.153
k0mar0v.ru. 3547 IN A 185.199.110.153
k0mar0v.ru. 3547 IN A 185.199.109.153
k0mar0v.ru. 3547 IN A 185.199.108.153