Lưu trữ

Quartz có thể biến các tệp Markdown và các tài nguyên khác của bạn thành một tập hợp các tệp HTML, JS và CSS (một trang web!).

Tuy nhiên, nếu bạn muốn xuất bản trang web của mình ra thế giới, bạn cần một cách để lưu trữ trực tuyến. Hướng dẫn này sẽ trình bày chi tiết cách triển khai với các nhà cung cấp dịch vụ lưu trữ phổ biến nhưng bất kỳ dịch vụ nào cho phép bạn triển khai HTML tĩnh cũng có thể hoạt động.

Phần còn lại của hướng dẫn này giả định rằng bạn đã tạo kho lưu trữ GitHub của riêng mình cho Quartz. Nếu bạn chưa tạo, hãy đảm bảo rằng bạn đã làm như vậy .

Một số tính năng của Quartz (như RSS Feed và tạo sitemap) cần baseUrlđược cấu hình đúng trong cấu hình của bạn để hoạt động bình thường. Hãy đảm bảo bạn thiết lập điều này trước khi triển khai!

Các trang Cloudflare

Đăng nhập vào bảng điều khiển Cloudflare và chọn tài khoản của bạn.
Trong Trang chủ tài khoản, chọn Công nhân & Trang > Tạo ứng dụng > Trang > Kết nối với Git .
Chọn kho lưu trữ GitHub mới mà bạn đã tạo và trong phần Thiết lập bản dựng và triển khai , hãy cung cấp thông tin sau:

Tùy chọn cấu hình	Giá trị
Chi nhánh sản xuất	`v4`
Khung cài đặt trước	`None`
Xây dựng lệnh	`npx quartz build`
Xây dựng thư mục đầu ra	`public`

Nhấn “Lưu và triển khai” và Cloudflare sẽ có phiên bản triển khai của trang web của bạn trong khoảng một phút. Sau đó, mỗi lần bạn đồng bộ hóa các thay đổi Quartz của mình với GitHub, trang web của bạn sẽ được cập nhật.

Để thêm tên miền tùy chỉnh, hãy tham khảo tài liệu của Cloudflare .

Theo mặc định, Cloudflare Pages sẽ thực hiện một bản sao nông, vì vậy nếu bạn dựa vào gitdấu thời gian, bạn nên thêm git fetch --unshallow &&vào đầu lệnh dựng (ví dụ: git fetch --unshallow && npx quartz build).

Trang GitHub

Trong Quartz cục bộ của bạn, hãy tạo một tệp mới quartz/.github/workflows/deploy.yml.

quartz/.github/workflows/deploy.yml

<span data-line=""><span>name</span><span>: </span><span>Deploy Quartz site to GitHub Pages</span></span>
<span data-line=""> </span>
<span data-line=""><span>on</span><span>:</span></span>
<span data-line=""><span>  push</span><span>:</span></span>
<span data-line=""><span>    branches</span><span>:</span></span>
<span data-line=""><span>      - </span><span>v4</span></span>
<span data-line=""> </span>
<span data-line=""><span>permissions</span><span>:</span></span>
<span data-line=""><span>  contents</span><span>: </span><span>read</span></span>
<span data-line=""><span>  pages</span><span>: </span><span>write</span></span>
<span data-line=""><span>  id-token</span><span>: </span><span>write</span></span>
<span data-line=""> </span>
<span data-line=""><span>concurrency</span><span>:</span></span>
<span data-line=""><span>  group</span><span>: </span><span>"pages"</span></span>
<span data-line=""><span>  cancel-in-progress</span><span>: </span><span>false</span></span>
<span data-line=""> </span>
<span data-line=""><span>jobs</span><span>:</span></span>
<span data-line=""><span>  build</span><span>:</span></span>
<span data-line=""><span>    runs-on</span><span>: </span><span>ubuntu-22.04</span></span>
<span data-line=""><span>    steps</span><span>:</span></span>
<span data-line=""><span>      - </span><span>uses</span><span>: </span><span>actions/checkout@v4</span></span>
<span data-line=""><span>        with</span><span>:</span></span>
<span data-line=""><span>          fetch-depth</span><span>: </span><span>0</span><span> # Fetch all history for git info</span></span>
<span data-line=""><span>      - </span><span>uses</span><span>: </span><span>actions/setup-node@v4</span></span>
<span data-line=""><span>        with</span><span>:</span></span>
<span data-line=""><span>          node-version</span><span>: </span><span>22</span></span>
<span data-line=""><span>      - </span><span>name</span><span>: </span><span>Install Dependencies</span></span>
<span data-line=""><span>        run</span><span>: </span><span>npm ci</span></span>
<span data-line=""><span>      - </span><span>name</span><span>: </span><span>Build Quartz</span></span>
<span data-line=""><span>        run</span><span>: </span><span>npx quartz build</span></span>
<span data-line=""><span>      - </span><span>name</span><span>: </span><span>Upload artifact</span></span>
<span data-line=""><span>        uses</span><span>: </span><span>actions/upload-pages-artifact@v3</span></span>
<span data-line=""><span>        with</span><span>:</span></span>
<span data-line=""><span>          path</span><span>: </span><span>public</span></span>
<span data-line=""> </span>
<span data-line=""><span>  deploy</span><span>:</span></span>
<span data-line=""><span>    needs</span><span>: </span><span>build</span></span>
<span data-line=""><span>    environment</span><span>:</span></span>
<span data-line=""><span>      name</span><span>: </span><span>github-pages</span></span>
<span data-line=""><span>      url</span><span>: </span><span>${{ steps.deployment.outputs.page_url }}</span></span>
<span data-line=""><span>    runs-on</span><span>: </span><span>ubuntu-latest</span></span>
<span data-line=""><span>    steps</span><span>:</span></span>
<span data-line=""><span>      - </span><span>name</span><span>: </span><span>Deploy to GitHub Pages</span></span>
<span data-line=""><span>        id</span><span>: </span><span>deployment</span></span>
<span data-line=""><span>        uses</span><span>: </span><span>actions/deploy-pages@v4</span></span>

Sau đó:

Đi đến tab “Settings” của kho lưu trữ phân nhánh của bạn và trong thanh bên, nhấp vào “Pages”. Trong “Source”, chọn “GitHub Actions”.
Cam kết những thay đổi này bằng cách thực hiện npx quartz sync. Điều này sẽ triển khai trang web của bạn tới <github-username>.github.io/<repository-name>.

Nếu bạn nhận được lỗi không được phép triển khai github-pagesdo các quy tắc bảo vệ môi trường, hãy đảm bảo bạn xóa mọi môi trường trang GitHub hiện có.

Bạn có thể thực hiện việc này bằng cách vào trang Cài đặt trên GitHub fork của bạn và vào tab Môi trường và nhấn vào biểu tượng thùng rác. Hành động GitHub sẽ tạo lại môi trường cho bạn một cách chính xác vào lần tiếp theo bạn đồng bộ hóa Quartz.

Quartz generates files in the format of file.html instead of file/index.html which means the trailing slashes for non-folder paths are dropped. As GitHub pages does not do this redirect, this may cause existing links to your site that use trailing slashes to break. If not breaking existing links is important to you (e.g. you are migrating from Quartz 3), consider using Cloudflare Pages.

Custom Domain

Here’s how to add a custom domain to your GitHub pages deployment.

Head to the “Settings” tab of your forked repository.
In the “Code and automation” section of the sidebar, click “Pages”.
Under “Custom Domain”, type your custom domain and click “Save”.
This next step depends on whether you are using an apex domain (example.com) or a subdomain (subdomain.example.com).
- If you are using an apex domain, navigate to your DNS provider and create an A record that points your apex domain to GitHub’s name servers which have the following IP addresses:
  - 185.199.108.153
  - 185.199.109.153
  - 185.199.110.153
  - 185.199.111.153
- If you are using a subdomain, navigate to your DNS provider and create a CNAME record that points your subdomain to the default domain for your site. For example, if you want to use the subdomain quartz.example.com for your user site, create a CNAME record that points quartz.example.com to <github-username>.github.io.

The above shows a screenshot of Google Domains configured for both jzhao.xyz (an apex domain) and quartz.jzhao.xyz (a subdomain).

See the GitHub documentation for more detail about how to setup your own custom domain with GitHub Pages.

Why aren't my changes showing up?

There could be many different reasons why your changes aren’t showing up but the most likely reason is that you forgot to push your changes to GitHub.

Make sure you save your changes to Git and sync it to GitHub by doing npx quartz sync. This will also make sure to pull any updates you may have made from other devices so you have them locally.

Vercel

Fix URLs

Before deploying to Vercel, a vercel.json file is required at the root of the project directory. It needs to contain the following configuration so that URLs don’t require the .html extension:

vercel.json

<span data-line=""><span>{</span></span>
<span data-line=""><span>  "cleanUrls"</span><span>: </span><span>true</span></span>
<span data-line=""><span>}</span></span>

Deploy to Vercel

Log in to the Vercel Dashboard and click “Add New…” > Project
Import the Git repository containing your Quartz project.
Give the project a name (lowercase characters and hyphens only)
Check that these configuration options are set:

Configuration option	Value
Framework Preset	`Other`
Root Directory	`./`
Build and Output Settings > Build Command	`npx quartz build`

Press Deploy. Once it’s live, you’ll have 2 *.vercel.app URLs to view the page.

Custom Domain

If there is something already hosted on the domain, these steps will not work without replacing the previous content. As a workaround, you could use Next.js rewrites or use the next section to create a subdomain.

Update the baseUrl in quartz.config.js if necessary.
Truy cập trang Bảng điều khiển - Tên miền trong Vercel.
Kết nối miền với Vercel
Nhấn “Thêm” để kết nối tên miền tùy chỉnh với Vercel.
Chọn kho lưu trữ Quartz của bạn và nhấn Tiếp tục.
Nhập tên miền mà bạn muốn kết nối tới.
Làm theo hướng dẫn để cập nhật bản ghi DNS của bạn cho đến khi bạn thấy “Cấu hình hợp lệ”

Sử dụng tên miền phụ

Sử dụng docs.example.comlà một ví dụ về tên miền phụ. Đây là cách đơn giản để kết nối nhiều triển khai vào một tên miền.

Cập nhật thông baseUrltin quartz.config.jsnếu cần thiết.
Đảm bảo tên miền của bạn đã được thêm vào trang Bảng điều khiển tên miền trong Vercel.
Truy cập Bảng điều khiển Vercel và chọn dự án Quartz của bạn.
Vào tab Cài đặt rồi nhấp vào Tên miền trong thanh bên
Nhập tên miền phụ của bạn vào trường và nhấn Thêm

Mạng lưới

Đăng nhập vào bảng điều khiển Netlify và nhấp vào “Thêm trang web mới”.
Chọn nhà cung cấp Git và kho lưu trữ chứa dự án Quartz của bạn.
Trong “Lệnh xây dựng”, nhập npx quartz build.
Trong “Xuất bản thư mục”, hãy nhập public.
Nhấn Deploy. Khi trang đã hoạt động, bạn sẽ có *.netlify.appURL để xem trang.
Để thêm tên miền tùy chỉnh, hãy chọn “Quản lý tên miền” ở thanh bên trái, giống như Vercel.

Trang GitLab

Trong Quartz cục bộ của bạn, hãy tạo một tệp mới .gitlab-ci.yml.

.gitlab-ci.yml

<span data-line=""><span>stages</span><span>:</span></span>
<span data-line=""><span>  - </span><span>build</span></span>
<span data-line=""><span>  - </span><span>deploy</span></span>
<span data-line=""> </span>
<span data-line=""><span>image</span><span>: </span><span>node:20</span></span>
<span data-line=""><span>cache</span><span>: </span><span># Cache modules in between jobs</span></span>
<span data-line=""><span>  key</span><span>: </span><span>$CI_COMMIT_REF_SLUG</span></span>
<span data-line=""><span>  paths</span><span>:</span></span>
<span data-line=""><span>    - </span><span>.npm/</span></span>
<span data-line=""> </span>
<span data-line=""><span>build</span><span>:</span></span>
<span data-line=""><span>  stage</span><span>: </span><span>build</span></span>
<span data-line=""><span>  rules</span><span>:</span></span>
<span data-line=""><span>    - </span><span>if</span><span>: </span><span>'$CI_COMMIT_REF_NAME == "v4"'</span></span>
<span data-line=""><span>  before_script</span><span>:</span></span>
<span data-line=""><span>    - </span><span>hash -r</span></span>
<span data-line=""><span>    - </span><span>npm ci --cache .npm --prefer-offline</span></span>
<span data-line=""><span>  script</span><span>:</span></span>
<span data-line=""><span>    - </span><span>npx quartz build</span></span>
<span data-line=""><span>  artifacts</span><span>:</span></span>
<span data-line=""><span>    paths</span><span>:</span></span>
<span data-line=""><span>      - </span><span>public</span></span>
<span data-line=""><span>  tags</span><span>:</span></span>
<span data-line=""><span>    - </span><span>gitlab-org-docker</span></span>
<span data-line=""> </span>
<span data-line=""><span>pages</span><span>:</span></span>
<span data-line=""><span>  stage</span><span>: </span><span>deploy</span></span>
<span data-line=""><span>  rules</span><span>:</span></span>
<span data-line=""><span>    - </span><span>if</span><span>: </span><span>'$CI_COMMIT_REF_NAME == "v4"'</span></span>
<span data-line=""><span>  script</span><span>:</span></span>
<span data-line=""><span>    - </span><span>echo "Deploying to GitLab Pages..."</span></span>
<span data-line=""><span>  artifacts</span><span>:</span></span>
<span data-line=""><span>    paths</span><span>:</span></span>
<span data-line=""><span>      - </span><span>public</span></span>

Khi .gitlab-ci.yamlđã cam kết, GitLab sẽ xây dựng và triển khai trang web dưới dạng GitLab Page. Bạn có thể tìm thấy url bên dưới Deploy > Pagestrong thanh bên.

Theo mặc định, trang này là riêng tư và chỉ hiển thị khi đăng nhập vào tài khoản GitLab có quyền truy cập vào kho lưu trữ nhưng có thể mở trong phần cài đặt bên dưới Deploy → Pages .

Tự lưu trữ

Sao chép publicthư mục vào máy chủ web của bạn và cấu hình nó để phục vụ các tệp. Bạn có thể sử dụng bất kỳ máy chủ web nào để lưu trữ trang web của mình. Vì Quartz tạo ra các liên kết không bao gồm phần .htmlmở rộng, bạn cần cho máy chủ web của mình biết cách xử lý nó.

Sử dụng Nginx

Sau đây là ví dụ về cách thực hiện việc này với Nginx:

nginx.conf

<span data-line=""><span>server</span><span> {</span></span>
<span data-line=""><span>    listen </span><span>80</span><span>;</span></span>
<span data-line=""><span>    server_name </span><span>example.com;</span></span>
<span data-line=""><span>    root </span><span>/path/to/quartz/public;</span></span>
<span data-line=""><span>    index </span><span>index.html;</span></span>
<span data-line=""><span>    error_page </span><span>404</span><span> /404.html;</span></span>
<span data-line=""> </span>
<span data-line=""><span>    location</span><span> / </span><span>{</span></span>
<span data-line=""><span>        try_files </span><span>$uri $uri.html $uri/ </span><span>=404</span><span>;</span></span>
<span data-line=""><span>    }</span></span>
<span data-line=""><span>}</span></span>

Sử dụng Caddy

Sau đây là ví dụ về cách thực hiện việc này với Caddy:

Hồ sơ Caddy

<span data-line=""><span>example.com {</span></span>
<span data-line=""><span>    root * /path/to/quartz/public</span></span>
<span data-line=""><span>    try_files {path} {path}.html {path}/ =404</span></span>
<span data-line=""><span>    file_server</span></span>
<span data-line=""><span>    encode gzip</span></span>
<span data-line=""> </span>
<span data-line=""><span>    handle_errors {</span></span>
<span data-line=""><span>        rewrite * /{err.status_code}.html</span></span>
<span data-line=""><span>        file_server</span></span>
<span data-line=""><span>    }</span></span>
<span data-line=""><span>}</span></span>

Các trang Cloudflare​

Trang GitHub​

Custom Domain​

Vercel​

Fix URLs​

Deploy to Vercel​

Custom Domain​

Sử dụng tên miền phụ​

Mạng lưới​

Trang GitLab​

Tự lưu trữ​

Sử dụng Nginx​

Sử dụng Caddy​

Các trang Cloudflare

Trang GitHub

Custom Domain

Vercel

Fix URLs

Deploy to Vercel

Custom Domain

Sử dụng tên miền phụ

Mạng lưới

Trang GitLab

Tự lưu trữ

Sử dụng Nginx

Sử dụng Caddy