Deploying Quartz to the Web

Last updated Jul 8, 2023 Edit Source

• Setup

Quartz is designed to be effortless to deploy. If you forked and cloned Quartz directly from the repository, everything should already be good to go! Follow the steps below.

By default, GitHub disables workflows from modifying your files (for good reason!). However, Quartz needs this to write the actual site files back to GitHub.

Head to Settings > Action > General > Workflow Permissions and choose Read and Write Permissions

github-actions.png Enable GitHub Actions

Head to the ‘Settings’ tab of your forked repository and go to the ‘Pages’ tab.

1. (IMPORTANT) Set the source to deploy from master (and not hugo) using / (root)
2. Set a custom domain here if you have one!

Enable GitHub Pages

To see your changes on the internet, we need to push it them to GitHub. Quartz is a git repository so updating it is the same workflow as you would follow as if it were just a regular software project.

1
2
3
4
5
6
7
8
9

# Navigate to Quartz folder
cd <path-to-quartz>

# Commit all changes
git add .
git commit -m "message describing changes"

# Push to GitHub to update site
git push origin hugo

Note: we specifically push to the hugo branch here. Our GitHub action automatically runs everytime a push to is detected to that branch and then updates the master branch for redeployment.

Now let’s get this site up and running. Never hosted a site before? No problem. Have a fancy custom domain you already own or want to subdomain your Quartz? That’s easy too.

Here, we take advantage of GitHub’s free page hosting to deploy our site. Change baseURL in /config.toml.

Make sure that your baseURL has a trailing /!

Reference config.toml here

1

baseURL = "https://<YOUR-DOMAIN>/"

If you are using this under a subdomain (e.g. <YOUR-GITHUB-USERNAME>.github.io/quartz), include the trailing /. You need to do this especially if you are using GitHub!

1

baseURL = "https://<YOUR-GITHUB-USERNAME>.github.io/quartz/"

Change cname in /.github/workflows/deploy.yaml. Again, if you don’t have a custom domain to use, you can use <YOUR-USERNAME>.github.io.

Please note that the cname field should not have any path e.g. end with /quartz or have a trailing /.

Reference deploy.yaml here

1
2
3
4
5
6
7

- name: Deploy  
  uses: peaceiris/actions-gh-pages@v3  
  with:  
	github_token: ${{ secrets.GITHUB_TOKEN }} # this can stay as is, GitHub fills this in for us!
	publish_dir: ./public  
	publish_branch: master
	cname: <YOUR-DOMAIN>

Have a custom domain? Learn how to set it up with Quartz .

Only want to publish a subset of all of your notes? Don’t worry, Quartz makes this a simple two-step process.

❌ Excluding pages from being published

If you don’t want to use a hosting service, you can host using Docker instead! I would not use this method unless you know what you are doing.

Now that your Quartz is live, let’s figure out how to make Quartz really yours!

Step 6: 🎨 Customizing Quartz

Having problems? Checkout our FAQ and Troubleshooting guide.