Why Z

中/EN

04. Syncing Obsidian files to Quartz

6 min read

Sync options

Option 1: fswatch real-time watching

  • What it is: publishes the moment you change a file
  • Downside: too frequent! It publishes every time you change a single character — a waste of resources
  • Good for: scenarios that need real-time updates

Option 2: crontab scheduled publishing

  • What it is: publishes once a day at a fixed time
  • Downside: the machine has to stay on — it won’t run while shut down
  • Good for: a Mac that’s usually powered on

Option 3: Git + GitHub Actions ⭐️ most recommended

  • What it is: manage your docs with Git; pushing to GitHub publishes automatically
  • Pros:
    • The Mac doesn’t need to stay on
    • Version control, so you can roll back
    • More professional and more stable
    • Just push manually whenever you want to publish
  • Good for: every scenario I’ve finished Option 1; I’ll keep tinkering with Option 3 when I have time.

Asked the AI and it gave me a solution fast — no excuse to be lazy now -.-//

2025-11-21 I found a single command that syncs both local repos and publishes in one run; just schedule it to run automatically and you’re done. I ended up choosing Option 3. The first time I tried it, it just wouldn’t work; this time it worked quickly. As expected, grinding too stubbornly isn’t always a good thing.

Watcher tools compared

ToolRatingProsGood for
chokidar-cli⭐⭐⭐⭐⭐Lightweight, cross-platform, Quartz’s defaultMost recommended
fswatch⭐⭐⭐⭐Best performance on MacMac users
nodemon⭐⭐⭐Clear logsPeople who want logs
Syncthing⭐⭐⭐⭐No code, auto-syncJust want file sync

Option 3

1. Install fswatch

# Install
brew install fswatch
 
# Confirm the install
fswatch --version

2. Initialize the Git repo

cd /Users/jz/quartz
git init
git add .
git commit -m "initial commit"

3. Connect to GitHub

# Skip these if you've already done them before
git remote add origin https://github.com/你的用户名/my-quartz.git
git branch -M main
git push -u origin main

4. Create a quick-publish script

nano ~/github-push.sh

Paste this (change the repo path to your own):

#!/bin/bash
 
# 设置环境变量,让 cron 能找到 npx ,提示找不到npx,但是能发布成功,下次再试试,如果一直成功就不改了
export PATH="/usr/local/bin:$PATH"
 
# 先同步 Obsidian 文件到 Quartz
OBSIDIAN_VAULT="/Users/jz/Library/Mobile Documents/iCloud~md~obsidian/Documents/all-in/2.Read"
QUARTZ_CONTENT="/Users/jz/quartz/content/2.Read"
# Quartz 项目根目录
QUARTZ_DIR="/Users/jz/quartz"
 
echo "$(date): 开始同步" 
cp -r "$OBSIDIAN_VAULT"/* "$QUARTZ_CONTENT/"
 
# 进入 Quartz 目录
cd "$QUARTZ_DIR"
 
# Git 提交并推送
echo "提交到 Git..."
git add .
git commit -m "update $(date +%Y-%m-%d-%H:%M)"
git push
 
echo "发布到线上..."
npx quartz sync --no-pull
 
echo "完成!"

This only replaces files with the same name; it won’t delete files that differ.

5. Make it executable

chmod +x ~/github-push.sh

6. Publish manually

~/github-push.sh

7. Auto-publish on a schedule

crontab

# 临时编辑器
EDITOR=nano crontab -e
# 每分钟执行
* * * * * /bin/bash ~/github-push.sh >> ~/cron-test.log 2>&1
  
  # 选择适合的自动发布时间
**每天上午10点执行:** 
 0 10 * * * /bin/bash ~/github-push.sh >> ~/cron-test.log 2>&1
**每两天上午10点执行:**
 0 10 */2 * * /bin/bash ~/github-push.sh >> ~/cron-test.log 2>&1
**每周四上午10点执行:**
0 10 * * 4 /bin/bash ~/github-push.sh >> ~/cron-test.log 2>&1
 
# 查看日志
cat ~/cron-test.log
# 清空日志
> ~/cron-test.log

Common commands

 
# 编辑当前用户的定时任务
crontab -e
 
# 查看当前用户的定时任务
crontab -l
 
# 删除当前用户的所有定时任务
crontab -r
 
# 编辑指定用户的定时任务(需要 root 权限)
sudo crontab -u username -e

Option 1

Windows version

2. Usage

Obsidian path: /Users/jz/Library/Mobile\ Documents/iCloud~md~obsidian/Documents/all\ in/2.Read Quartz path: /Users/jz/quartz/content/2.Read

2.1 Create an automation script to sync the two local repos

Open the terminal (create a text file):

nano ~/sync-quartz.sh

Copy and paste the following in:

#!/bin/bash
 
# Obsidian 路径(iCloud 同步的)
OBSIDIAN_VAULT="/Users/jz/Library/Mobile Documents/iCloud~md~obsidian/Documents/all-in/2.Read"
 
# Quartz 内容路径
QUARTZ_CONTENT="/Users/jz/quartz/content/2.Read"
 
# Quartz 项目根目录
QUARTZ_DIR="/Users/jz/quartz"
 
# 记录日志
echo "$(date): 开始同步" >> ~/quartz-sync.log
 
# 复制文件到 Quartz
cp -r "$OBSIDIAN_VAULT"/* "$QUARTZ_CONTENT/"
 
# 进入 Quartz 目录并发布
cd "$QUARTZ_DIR"
/usr/local/bin/npx quartz sync --no-pull
 
echo "$(date): 同步完成" >> ~/quartz-sync.log

Windows: press Ctrl + X, then Y, then Enter to save Mac: press control + X, then Y, then Enter to save

2.2 Make the script runnable

chmod +x ~/sync-quartz.sh

2.3 Test it once manually

~/sync-quartz.sh

2.4 Set it to run daily

crontab -e
 
# Run (every day at 2 AM):
0 2 * * * /Users/jz/sync-quartz.sh

Save and exit (Ctrl+X, then Y, then Enter) If crontab -e shows no options / you can’t edit after entering it:

# When crontab -e shows no options
export EDITOR=nano

On Mac you can use launchd

Don’t set up too many — crontab is usually enough, otherwise it gets hard to manage.

1. Create the launchd config file

nano ~/Library/LaunchAgents/com.user.sync-quartz.plist

2. Paste the config

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.user.sync-quartz</string>
 
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>/Users/jz/sync-quartz.sh</string>
    </array>
 
    <!-- 每天凌晨2点运行 -->
    <key>StartCalendarInterval</key>
    <dict>
        <key>Hour</key>
        <integer>2</integer>
        <key>Minute</key>
        <integer>0</integer>
    </dict>
 
    <!-- 日志文件 -->
    <key>StandardOutPath</key>
    <string>/Users/jz/logs/sync-quartz.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/jz/logs/sync-quartz-error.log</string>
 
    <!-- 即使上次运行失败也继续运行 -->
    <key>RunAtLoad</key>
    <false/>
</dict>
</plist>

3. Create the log directory

mkdir -p ~/logs

4. Load and start the job

# 加载任务
launchctl load ~/Library/LaunchAgents/com.user.sync-quartz.plist
 
# 检查是否加载成功
launchctl list | grep sync-quartz

5. Run a test immediately

# 手动触发一次
launchctl start com.user.sync-quartz
 
# 查看日志
cat ~/logs/sync-quartz.log
cat ~/logs/sync-quartz-error.log

6. Run on a schedule

<!-- 每小时运行 -->
<key>StartInterval</key>
<integer>3600</integer>
 
<!-- 或者每天多次运行(早8点和晚8点) -->
<key>StartCalendarInterval</key>
<array>
    <dict>
        <key>Hour</key>
        <integer>8</integer>
        <key>Minute</key>
        <integer>0</integer>
    </dict>
    <dict>
        <key>Hour</key>
        <integer>20</integer>
        <key>Minute</key>
        <integer>0</integer>
    </dict>
</array>

Common commands

# 停止任务
launchctl stop com.user.sync-quartz
 
# 卸载任务
launchctl unload ~/Library/LaunchAgents/com.user.sync-quartz.plist
 
# 重新加载(修改配置后)
launchctl unload ~/Library/LaunchAgents/com.user.sync-quartz.plist
launchctl load ~/Library/LaunchAgents/com.user.sync-quartz.plist
 
# 查看当前用户的所有任务 
launchctl list | wc -l
 
# 查看任务状态
launchctl list | grep sync-quartz
 
# 启动任务(立即执行一次)
launchctl start com.example.myscript
 
# 停止任务
launchctl stop com.example.myscript
 
# 查看所有已加载的任务
launchctl list
 
# 查看特定任务状态
launchctl list | grep com.example
 
# 查看任务详细信息
launchctl print gui/$(id -u)/com.example.myscript
 
# 移除任务
launchctl remove com.example.myscript

Backlinks