PDCXS

Quarzd 配置教程记录

5分钟阅读

本项目是依赖 Quartz项目实现的，整个实现过程记录如下。

项目初始化

按照官网的说法，执行以下命令

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

然后一切按照默认选择即可。

注意，按照官网设置发布的网址会有一个仓库的网址，如 pdcxs.github.io/quartz，如果想直接发布到 username.github.io， 参见 使用根域名。

配置内容

首先，需要删除 doc 目录。这是帮助文件，删除可以减少体积。

其次，需要将 quartz.config.tx中的以下选项分别改为对应值：

选项名称更改内容
pageTitle网站名称
locale”zh-CN”
baseUrl要发部的网址，不要加 http

注意，如果在 github 上发部， baseUrl 需要加项目名称。例如，我的用户名为 pdcxs，我的仓库名为 quartz，则 baseUrl 应当为： pdcxs.github.io/quartz。

更改字体

直接在配置文件中更改字体有两个限制：

  1. 只能使用 Google Fonts，能使用的字体有限。
  2. 同样是因为 Google Fonts，国内访问可能有问题。

因此，需要直接更改 quartz/styles/custom.scss 的内容。

例如，本项目使用了霞鹜文楷字体。查看国内CDN的内容，直接将其内容拷贝到 custom.scss中即可。

例如，我的部分文件内容如下：

@use "./base.scss";
 
// put your custom CSS here!
 
/* LXGW WenKai [4] */
@font-face {
  font-family: "LXGW WenKai";
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url("https://cdn.jsdelivr.net/npm/lxgw-wenkai-webfont@1.6.0/files/lxgwwenkai-regular-subset-4.woff2")
    format("woff2");
  unicode-range:
    U+1f1e9-1f1f5, U+1f1f7-1f1ff, U+1f21a, U+1f232, U+1f234-1f237, U+1f250-1f251, U+1f300,
    U+1f302-1f308, U+1f30a-1f311, U+1f315, U+1f319-1f320, U+1f324, U+1f327, U+1f32a, U+1f32c-1f32d,
    U+1f330-1f357, U+1f359-1f37e;
}
/* LXGW WenKai [5] */
@font-face {
  font-family: "LXGW WenKai";
  font-style: normal;
  font-weight: 400;
  font-display: swap;
  src: url("https://cdn.jsdelivr.net/npm/lxgw-wenkai-webfont@1.6.0/files/lxgwwenkai-regular-subset-5.woff2")
    format("woff2");
  unicode-range:
    U+fee3, U+fef3, U+ff03-ff04, U+ff07, U+ff0a, U+ff17-ff19, U+ff1c-ff1d, U+ff20-ff3a, U+ff3c,
    U+ff3e-ff5b, U+ff5d, U+ff61-ff65, U+ff67-ff6a, U+ff6c, U+ff6f-ff78, U+ff7a-ff7d, U+ff80-ff84,
    U+ff86, U+ff89-ff8e, U+ff92, U+ff97-ff9b, U+ff9d-ff9f, U+ffe0-ffe4, U+ffe6, U+ffe9, U+ffeb,
    U+ffed, U+fffc, U+1f004, U+1f170-1f171, U+1f192-1f195, U+1f198-1f19a, U+1f1e6-1f1e8;
 
  // 后面内容为在线 css 的内容的拷贝
}

最后，在 custom.scss 文件中，加入以下内容即可：

:root {
  --bodyFont: "LXGW WenKai" !important;
  --headerFont: "LXGW WenKai" !important;
  --codeFont: "Cascadia Code" !important;
}

最后，执行以下命令：

npx quartz build --serve

即可在浏览器中打开http://localhost:8080/查看效果了。

上传 github

参考官网，先新建一个名为 quartz 的仓库，不要包含 README、.gitignore 和 LICENSE。

按照git如何设置远程接入地址中的方法，设置好远程地址。

需要再执行以下命令来删除 upstream 地址：

git remote rm upstream

最后，执行以下命令：

npx quartz sync --no-pull

部署

按照官网指示，新建文件 quartz/.github/workflows/deploy.yml，在其中添加以下内容：

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@v4
        with:
          fetch-depth: 0 # Fetch all history for git info
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Dependencies
        run: npm ci
      - name: Build Quartz
        run: npx quartz build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        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@v4

在 GitHub 项目设置中，选择 Settings -> Pages -> Source -> Github Actions

之后再执行以下命令同步：

npx quartz sync

使用根域名

如果想直接使用 user.github.io 作为项目域名，则需要：

  1. 仓库名称改为：[username].github.io
  2. 设置项中的 baseUrl 设置为 [username].github.io (不要加 https)
  3. pages 设置为 Deploy from a branch，Branch 选择为 main / root。
  4. deploy.yml 内容改为：
name: Deploy Quartz site to GitHub Pages
 
on:
  push:
    branches:
      - v4
 
permissions:
  contents: write
  pages: write
  id-token: write
 
concurrency:
  group: "pages"
  cancel-in-progress: false
 
jobs:
  build:
    runs-on: ubuntu-22.04
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Fetch all history for git info
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - name: Install Dependencies
        run: npm ci
      - name: Build Quartz
        run: npx quartz build
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: public
      - name: Push to main branch
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./public
          publish_branch: main
          force_orphan: true
          keep_files: false

其它按照之前的步骤进行即可。

单独配置主页

如何仅在 Quartz 的主页添加 RecentNotes

在配置Quartz时，想要只在主页显示 RecentNotes，后来发现可以使用 Component.ConditionalRender 来实现这一效果。 quartz.layout.ts 内容如下：

如何仅在 quartz 的主页添加 RecentNotes.md

import { PageLayout, SharedLayout } from "./quartz/cfg"
import * as Component from "./quartz/components"
 
// components shared across all pages
export const sharedPageComponents: SharedLayout = {
  head: Component.Head(),
  header: [],
  afterBody: [
    Component.ConditionalRender({
      component: Component.RecentNotes({
        showTags: false,
        limit: 5,
      }),
      condition: (page) => page.fileData.slug === "index",
    }),
  ],
  footer: Component.Footer({
    links: {
      GitHub: "https://github.com/pdcxs",
      BiliBili: "https://space.bilibili.com/10707223",
    },
  }),
}
 
// components for pages that display a single page (e.g. a single note)
export const defaultContentPageLayout: PageLayout = {
  beforeBody: [
    Component.ConditionalRender({
      component: Component.Breadcrumbs(),
      condition: (page) => page.fileData.slug !== "index",
    }),
    Component.ArticleTitle(),
    Component.ContentMeta(),
    Component.TagList(),
  ],
  left: [
    Component.PageTitle(),
    Component.MobileOnly(Component.Spacer()),
    Component.Flex({
      components: [
        {
          Component: Component.Search(),
          grow: true,
        },
        { Component: Component.Darkmode() },
        { Component: Component.ReaderMode() },
      ],
    }),
    Component.Explorer(),
  ],
  right: [
    Component.Graph(),
    Component.DesktopOnly(Component.TableOfContents()),
    Component.Backlinks(),
  ],
}
 
// components for pages that display lists of pages  (e.g. tags or folders)
export const defaultListPageLayout: PageLayout = {
  beforeBody: [Component.Breadcrumbs(), Component.ArticleTitle(), Component.ContentMeta()],
  left: [
    Component.PageTitle(),
    Component.MobileOnly(Component.Spacer()),
    Component.Flex({
      components: [
        {
          Component: Component.Search(),
          grow: true,
        },
        { Component: Component.Darkmode() },
      ],
    }),
    Component.Explorer(),
  ],
  right: [],
}
指向原始笔记的链接

关系图谱

反向链接