---
Quartz effectively turns your Markdown files and other resources into a bundle of HTML, JS, and CSS files (a website!).
However, if you'd like to publish your site to the world, you need a way to host it online. This guide will detail how to deploy with common hosting providers but any service that allows you to deploy static HTML should work as well.
[!warning]
The rest of this guide assumes that you've already created your own GitHub repository for Quartz. If you haven't already, [[setting up your GitHub repository|make sure you do so]].[!hint]
Some Quartz features (like [[RSS Feed]] and sitemap generation) requirebaseUrlto be configured properly in your [[configuration]] to work properly. Make sure you set this before deploying!
| Configuration option | Value |
|---|---|
| Production branch | v4 |
| Framework preset | None |
| Build command | npx quartz build |
| Build output directory | public |
Press "Save and deploy" and Cloudflare should have a deployed version of your site in about a minute. Then, every time you sync your Quartz changes to GitHub, your site should be updated.
To add a custom domain, check out Cloudflare's documentation.
[!warning]
Cloudflare Pages performs a shallow clone by default, so if you rely ongitfor timestamps, it is recommended that you addgit fetch --unshallow &&to the beginning of the build command (e.g.,git fetch --unshallow && npx quartz build).
In your local Quartz, create a new file 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
- 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
Then:
npx quartz sync. This should deploy your site to <github-username>.github.io/<repository-name>.[!hint]
If you get an error about not being allowed to deploy togithub-pagesdue to environment protection rules, make sure you remove any existing GitHub pages environments.You can do this by going to your Settings page on your GitHub fork and going to the Environments tab and pressing the trash icon. The GitHub action will recreate the environment for you correctly the next time you sync your Quartz.
[!info]
Quartz generates files in the format offile.htmlinstead offile/index.htmlwhich 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]].
Here's how to add a custom domain to your GitHub pages deployment.
example.com) or a subdomain (subdomain.example.com).A record that points your apex domain to GitHub's name servers which have the following IP addresses:
185.199.108.153185.199.109.153185.199.110.153185.199.111.153CNAME 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.![[dns records.png]]_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.
[!question] 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.
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:
{
"cleanUrls": true
}
| Configuration option | Value |
|---|---|
| Framework Preset | Other |
| Root Directory | ./ |
| Build and Output Settings > Build Command | npx quartz build |
*.vercel.app URLs to view the page.[!note]
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.
baseUrl in quartz.config.js if necessary.Using docs.example.com is an example of a subdomain. They're a simple way of connecting multiple deployments to one domain.
baseUrl in quartz.config.js if necessary.npx quartz build.public.*.netlify.app URL to view the page.In your local Quartz, create a new file .gitlab-ci.yml.
stages:
- build
- deploy
image: node:20
cache: # Cache modules in between jobs
key: $CI_COMMIT_REF_SLUG
paths:
- .npm/
build:
stage: build
rules:
- if: '$CI_COMMIT_REF_NAME == "v4"'
before_script:
- hash -r
- npm ci --cache .npm --prefer-offline
script:
- npx quartz build
artifacts:
paths:
- public
tags:
- docker
pages:
stage: deploy
rules:
- if: '$CI_COMMIT_REF_NAME == "v4"'
script:
- echo "Deploying to GitLab Pages..."
artifacts:
paths:
- public
When .gitlab-ci.yaml is committed, GitLab will build and deploy the website as a GitLab Page. You can find the url under Deploy > Pages in the sidebar.
By default, the page is private and only visible when logged in to a GitLab account with access to the repository but can be opened in the settings under Deploy -> Pages.
Copy the public directory to your web server and configure it to serve the files. You can use any web server to host your site. Since Quartz generates links that do not include the .html extension, you need to let your web server know how to deal with it.
Here's an example of how to do this with Nginx:
server {
listen 80;
server_name example.com;
root /path/to/quartz/public;
index index.html;
error_page 404 /404.html;
location / {
try_files $uri $uri.html $uri/ =404;
}
}
Here's and example of how to do this with Caddy:
example.com {
root * /path/to/quartz/public
try_files {path} {path}.html {path}/ =404
file_server
encode gzip
handle_errors {
rewrite * /{err.status_code}.html
file_server
}
}