张芷铭的个人博客

#Obsidian #Quartz #静态网站 #博客

Quartz 是专为 Obsidian 设计的静态网站生成器，将 Markdown 笔记转化为可访问的网页，原生支持双链、图谱、标签。

官方文档：https://quartz.jzhao.xyz/ GitHub：https://github.com/jackyzha0/quartz

核心特性

  • 原生支持 Obsidian 语法：自动解析双链、标签、文件夹结构
  • 轻量高效：基于 Node.js，生成速度快
  • 内置知识图谱：可视化笔记关联
  • 响应式设计：适配多设备
  • 可定制：支持主题、布局、导航栏修改

快速开始

前置准备

  • Node.js v16+（推荐 v18）
  • Git
  • Obsidian 笔记库

安装

1
2
3

git clone https://github.com/jackyzha0/quartz.git
cd quartz
npm install

配置笔记路径

修改 quartz.config.ts：

1
2
3

export default {
  contentPath: "./my-obsidian-notes",  // Obsidian 笔记库路径
}

本地预览

1
2

npm run dev
# 访问 http://localhost:8080

自定义配置

修改主题

1
2
3
4

// quartz.config.ts
export default {
  theme: "dark",  // light / dark / academic
}

修改导航栏

编辑 quartz/layouts/partials/navbar.njk：

1

<a href="/about" class="nav-link">关于</a>

自定义样式

编辑 quartz/assets/styles/custom.scss：

1
2
3

.page-content {
  font-size: 18px;
}

部署

生成静态文件

1
2

npm run build
# 输出到 public 文件夹

部署平台

平台特点
GitHub Pages免费，需手动配置
Vercel自动识别，推荐

GitHub Actions 自动部署

创建 .github/workflows/deploy.yml：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

name: Deploy Quartz
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm install
      - run: npm run build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public

多媒体处理

  1. 统一存放于 attachments 文件夹
  2. 使用相对路径插入：
1
2

![截图](./attachments/screenshot.png)
<video src="./attachments/demo.mp4" controls></video>

自动化流程

Obsidian 写笔记 → Git 同步 → Quartz 构建 → 自动部署

安装 Obsidian Git 插件实现自动提交推送，配合 GitHub Actions 实现全自动更新。

Comments