使用Obisidian和Quartz 4编写博客

安装和配置Quartz 4

git clone https://github.com/Kuhbz/quartz.git
cd quartz
npm i
npx quartz create

Warning

我安装的是我修改后配置好后的版本，如果要安装官方的版本请把仓库地址替换为：https://github.com/jackyzha0/quartz.git

需要配置的插件

priority: 用于查询日期信息的数据源。优先级最高。可能值为"frontmatter"、"git"和"filesystem"。默认为["frontmatter", "git", "filesystem"]。如果您依赖git日期，请在quartz.config.ts设置defaultDateType设置modified。
HardLineBreaks: 此插件会自动将 Markdown 文本中的单行换行符转换为 HTML 输出中的硬换行符。由于此插件不符合实际 Markdown 的语义，因此默认不启用。但如果您想与Obisidian保持一致，可以启用它。

编写文章

元数据

Quartz 还允许在笔记中用Frontmatter的方式的附加元数据。

---
title: Example Title
draft: false
tags:
  - example-tag
---
 
The rest of your content lives here. You can use **Markdown** here :)

Quartz 原生支持的一些常见前置字段：

title：页面标题。如果没有提供，Quartz 将使用文件名称作为标题。
description：用于链接预览的页面描述。通常会被用在 SEO 的 meta 标签中，以及在文章列表或搜索结果中作为摘要显示
permalink：页面的自定义 URL，即使文件路径发生变化也将保持不变。
aliases：此笔记的其他名称。这是一个字符串列表。
tags：为页面打上一或多个标签。
draft：是否发布页面。
date：表示笔记发布日期的字符串。使用YYYY-MM-DD格式。
comments：设置为false则表示在本页不显示评论区。

预览

npx quartz build --serve --concurrency 8

要获得完整的帮助选项，可以运行npx quartz build --help。其中大多数都有合理的默认值，但是如果您有自定义设置，则可以覆盖它们：

-d或--directory：内容文件夹。这通常只是content
-v或--verbose：打印额外的日志信息
-o或--output：输出文件夹。这通常只是public
--serve：运行本地热重载服务器来预览你的 Quartz
--port：在哪个端口上运行本地预览服务器
--concurrency：使用多少个线程来解析笔记

提交更改

npx quartz sync

部署到Github Pages

为了方便访问，我把生成的静态文件单独部署到kuhbz.github.io中，并且Giscus也使用这个仓库的discussions。

1. 创建仓库

<你的用户名>.github.io 是一个特殊的仓库，GitHub 会自动将它的 main (或 master) 分支部署为你的用户主页。如果这个仓库还不存在，请先在你的 GitHub 上创建它。网址就是 https://<你的用户名>.github.io。举例：我的用户名为kuhbz，那么仓库名就是kuhbz.github.io，访问地址就是https://kuhbz.github.io

2. 生成并配置部署密钥

为了让你当前仓库的 Action 能够安全地推送到 kuhbz.github.io 仓库，最安全的方法是使用部署密钥（Deploy Keys）。

生成 SSH 密钥对： 在你的本地电脑上打开终端，运行以下命令来生成一个新的 SSH 密钥对。当提示输入文件名时，可以输入 deploy_key，并且不要设置密码（直接按回车）。
```
ssh-keygen -t ed25519 -N "" -f deploy_key
```
这会生成两个文件：deploy_key (私钥) 和 deploy_key.pub (公钥)。
添加公钥到 kuhbz.github.io 仓库：
- 打开 deploy_key.pub 文件，复制里面的全部内容。
- 进入 kuhbz.github.io 仓库的 GitHub 页面。
- 点击 “Settings” → “Deploy keys” → “Add deploy key”。
- 给它一个标题，比如 “Quartz Deploy”。
- 将公钥内容粘贴到 “Key” 字段中。
- 非常重要：勾选 “Allow write access” 复选框。
- 点击 “Add key”。
添加私钥到你当前 Quartz 仓库：
- 打开 deploy_key 文件（私钥），复制里面的全部内容。
- 进入你存放 Quartz 源码的仓库的 GitHub 页面。
- 点击 “Settings” → “Secrets and variables” → “Actions”。
- 点击 “New repository secret”。
- 将 Secret 的名字设置为 DEPLOY_KEY。
- 将私钥内容粘贴到 “Secret” 字段中。
- 点击 “Add secret”。

3. 创建 deploy.yml 工作流

现在，新建 .github/workflows/deploy.yml 文件。这个新版本的工作流使用了peaceiris/actions-gh-pages 这个流行的 Action 来处理跨仓库部署。

name: Deploy Quartz site to kuhbz.github.io
 
on:
  push:
    branches:
      - v4 # 确保这是你的源码主分支
 
jobs:
  build-and-deploy:
    runs-on: ubuntu-22.04
    steps:
      - name: Checkout source code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 获取所有git历史记录，用于日期等信息
 
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22
 
      - name: Install Dependencies
        run: npm ci
 
      - name: Build Quartz
        run: npx quartz build
 
      - name: Deploy to kuhbz.github.io
        uses: peaceiris/actions-gh-pages@v4
        with:
          # 这是我们上一步创建的私钥Secret
          deploy_key: ${{ secrets.DEPLOY_KEY }}
          # 这是你的目标仓库
          external_repository: kuhbz/kuhbz.github.io
          # 这是要部署的文件夹
          publish_dir: ./public
          # 这是目标仓库的分支，对于用户主页通常是 main 或 master
          publish_branch: main
          # 确保 CNAME 文件被保留（如果你使用自定义域名）
          keep_files: false
          # 提交代码的用户名和邮箱
          user_name: 'github-actions[bot]'
          user_email: 'github-actions[bot]@users.noreply.github.com'
          # 提交信息
          commit_message: "Deploy Quartz site from ${{ github.sha }}"

总结

完成以上步骤后：运行 npx quartz sync 来提交并推送你的更改。推送会触 GitHub Actions 工作流。它会：

构建你的 Quartz 网站，生成静态文件到 public 目录。
使用你配置的部署密钥，安全地将 public 目录下的所有内容推送到 kuhbz.github.io 仓库的 main 分支。稍等片刻，网站就会成功部署在 https://kuhbz.github.io 上了。有需要的话也可以配置自定义域名。

Kuhbz的博客

Kuhbz

使用Obisidian和Quartz 4编写博客

安装和配置Quartz 4

需要配置的插件

编写文章

元数据

预览

提交更改

部署到Github Pages

1. 创建仓库

2. 生成并配置部署密钥

3. 创建 deploy.yml 工作流

总结

目录