mirror of
https://github.com/jackyzha0/quartz.git
synced 2026-03-23 06:25:41 -05:00
100 lines
3.6 KiB
Markdown
100 lines
3.6 KiB
Markdown
---
|
||
type: engineering
|
||
topic: 生产力工具
|
||
project_status: 进行中
|
||
tags:
|
||
- "#project"
|
||
- "#engineering"
|
||
- "#demo"
|
||
created: 2026-02-10 16:35
|
||
updated: 2026-02-10 16:35
|
||
version: "1.0"
|
||
---
|
||
# 🏗️ 工程实战：Quartz V4 部署实战：从本地到公网的数字花园
|
||
|
||
> [!abstract] 项目意图
|
||
> - **目标**：将 Synapse-Vault 笔记库通过 Quartz v4 渲染成静态网站，并发布至 GitHub Pages。
|
||
> - **核心工具链**：Node.js (v18.14+), Quartz v4, GitHub Actions.
|
||
> - **当前版本**：V`=this.version`
|
||
|
||
## 🏁 环境准备 (Prerequisites)
|
||
|
||
- **运行环境**：(如 Node.js v18.14+, Python 3.10)
|
||
- **依赖安装**：
|
||
```bash
|
||
# 在克隆好的 quartz 目录下执行
|
||
npm install
|
||
```
|
||
|
||
## 💻 核心实现 (Core Implementation)
|
||
|
||
### 1. 初始化链接
|
||
|
||
在终端执行初始化向导，将 Quartz 代码仓库与 Obsidian 笔记库物理关联。
|
||
|
||
```Bash
|
||
npx quartz create
|
||
```
|
||
|
||
|
||
|
||
#### 🔍 选项深度对比
|
||
| 选项 | 对应行为 | 适合场景 |
|
||
| -------------------------- | --------------------------------------------------------------------- | ---------------------------------------------- |
|
||
| Empty Quartz | 建立一个空的内容目录 | 从零开始在 Quartz 文件夹里写笔记 |
|
||
| Copy an existing folder | **物理复制**。把你的笔记文件夹里的文件全部拷贝一份到 `quartz/content` | **推荐新手使用**。最稳定，不破坏原笔记库，也不怕路径权限问题 |
|
||
| Symlink an existing folder | **软链接**。即 `Link an existing Obsidian vault` 的本质。在 macOS 系统层建立一个“快捷方式” | **进阶使用**。实现“实时同步”，你在 Obsidian 改完，网页浏览直接刷新，无需复制 |
|
||
|
||
这里选择：`Link an existing Obsidian vault`（即第三个选项） 并输入笔记库绝对路径。
|
||
|
||
### 2. 跨仓库自动同步脚本 (GitHub Action)
|
||
|
||
在笔记仓库（Synapse-Vault）的 `.github/workflows/sync.yml` 中配置以下逻辑：
|
||
|
||
```Yaml
|
||
name: Sync to Quartz
|
||
on:
|
||
push:
|
||
branches: [ main ]
|
||
jobs:
|
||
repo-sync:
|
||
runs-on: ubuntu-latest
|
||
steps:
|
||
- name: Checkout
|
||
uses: actions/checkout@v3
|
||
- name: Pushing to Quartz Repo
|
||
uses: cpina/github-action-push-to-another-repository@main
|
||
env:
|
||
API_TOKEN_GITHUB: ${{ secrets.QUARTZ_SYNC_TOKEN }}
|
||
with:
|
||
source-directory: '.'
|
||
destination-github-username: '你的用户名'
|
||
destination-repository-name: 'quartz'
|
||
user-email: your-email@example.com
|
||
target-directory: 'content'
|
||
```
|
||
|
||
## 🚩 关键步骤与坑点 (Key Steps & Pitfalls)
|
||
|
||
1. **Node 版本**：Quartz v4 依赖较高版本的 Node，若 `npm i` 报错，请检查 `node -v`。
|
||
|
||
2. **符号链接 (Symlink)**：
|
||
|
||
- ⚠️ **踩坑提示**：Windows 系统下执行 `npx quartz create` 必须使用 **管理员权限** 运行终端，否则无法建立链接，导致 `content` 文件夹为空。
|
||
|
||
|
||
## 🧪 测试与验收 (Testing)
|
||
|
||
- **预期结果**：执行 `npx quartz build --serve` 后，本地 8081 端口可访问美化后的笔记网页。
|
||
|
||
- **实际表现**：
|
||
|
||
|
||
## 📓 复盘与迭代 (Review)
|
||
|
||
- **优化空间**：默认主题颜色需根据 Synapse-Vault 的风格进行 CSS 微调。
|
||
|
||
- **下一步计划**: [[下个迭代笔记名]]
|
||
|
||
---
|
||
#project #engineering |